MPS Console and the smodel query language

The MPS Console runs DSL code against the live models of the open project: query and mutate nodes, run find-usages, gather statistics, make/clean models, reload classes. Code is typed line-by-line, generated by the MPS generator, and executed in the IDE context. Most console-specific constructs start with # and completion (Ctrl+Space) inserts them.

The smodel query language (jetbrains.mps.lang.smodel.query) exposes the same queries (#nodes, #instances, #usages, …) for use in ordinary model code — intentions, behavior methods, actions, migration/refactoring scripts — wrapped in a with (<scope>) { … } statement. Reach for it whenever code needs to enumerate nodes/models/modules or find instances/usages across a scope.

Ways this skill gets used

1. Type code in the Console tool window (Tools ▸ Console, or the Console tool window). One command per input. See references/console-languages.md.
2. Write smodel.query queries inside model code (an intention, behavior method, generator query, script). Import jetbrains.mps.lang.smodel.query and wrap queries in with (<scope>) { … }. See references/smodel-query.md.
3. Insert code into the Console from an agent via mps_mcp_insert_console_command_from_json — builds a command from a JSON blueprint and drops it into the console input without executing it (the user reviews and runs it with Ctrl+Enter). See references/mcp-insertion.md.
4. Read the current Console command from an agent via mps_mcp_get_current_editor_root_node with source = "console" — returns the node-info envelope of the command currently in the console input (one an agent inserted, or the user typed). Feed its reference to mps_mcp_print_node for the JSON blueprint (format = "JSON") or the notational printout (format = "PLAIN TEXT" / "HTML"), or to mps_mcp_check_root_node_problems to see the problems MPS's model checker reports for it (way #8). The reference is only valid until the next console interaction (execute / clear / history navigation), so print it promptly and do not cache it.
5. Browse the Console history from an agent via mps_mcp_get_console_history — lists previously executed commands in order, each with a one-line preview, a history-entry reference, and an effectiveCommandReference. Pass the entry reference to recall; pass effectiveCommandReference to mps_mcp_print_node. Use includeResponses = true to also see the printed output. Same reference-validity caveat as #4.
6. Recall a history command into the input via mps_mcp_recall_console_command(historyNodeReference) — deep-copies a history entry (from #5) back into the input slot without executing it. Pass the history entry's reference, not its effectiveCommandReference. There is no MPS "recall" API to call directly; this mirrors what the Console's own up/down history navigation does (copy + insert).
7. Run the current Console command from an agent via mps_mcp_run_console_command — executes whatever command is currently in the input (placed there by #3 or #6, or typed by the user), exactly as Ctrl+Enter, and only when a command is present. It executes code with side effects. The response is not returned by the tool; read it afterwards via #5 (mps_mcp_get_console_history with includeResponses = true) or from the Console tool window, and note that long-running commands (make/generate) complete asynchronously.
8. Check a Console command for problems from an agent via mps_mcp_check_root_node_problems — pass the reference from way #4 (or an effectiveCommandReference from way #5) and it runs MPS's full checker set (structure, constraints, reference scopes, typesystem, and checking rules), surfacing the same errors/warnings the Console editor underlines and the Model Checker reports. Two caveats: (a) root-scoped — the tool checks the command's containingRoot, which for console code is the single ConsoleRoot holding the current input and the entire history, so results can include problems from earlier commands; with the default onlyNodesWithProblems = true you get a flat list of problem nodes, so match each one's rootName/subtree to the command you mean. (b) Same reference-validity window as #4 — resolve and check before the next console interaction.

A command is one of three shapes

The console input holds exactly one command (jetbrains.mps.console.base.structure.Command):

Key fact that trips up blueprints: the query commands (#nodes, #instances, …), the IDE commands #make / #clean / #removeGenSources / #show / #callAction, and the printers #print / #printNode / #printNodeRef / #printSequence / #printText are all baseLanguage Expressions, not Commands. To use one as a standalone command you put it inside a BLExpression (or inside { … } statements). Only InterpretedCommand subtypes and #reloadClasses are commands in their own right.

Critical Directives

• This skill is the controlling workflow for Console tasks. Start from surface syntax first — choose the query (#instances, #usages, #nodes, …), filter and transform with smodel / collections / closures, then insert or run via the console MCP tools. Only fall back to low-level Java/MPS-OpenAPI approaches if the surface syntax route has genuinely failed.
• Pick the scope deliberately. Without a scope, console queries run over all editable models of the current project; a with statement defaults to editable models too, so model-changing code is safe. Scopes: project, editable, global, visible, modules(...), models(...), custom(<SearchScope>). See references/smodel-query.md.
• scope parameter ≠ with scope. When you pass scope explicitly as a query parameter it is used as-is and keeps read-only models, so #nodes inside with(project) and #nodes<scope project> can return different results.
• No nested with. A with statement may not contain another with.
• Lazy vs eager: #nodes / #references / #models / #modules are lazy sequences (full iteration). #instances / #usages use the find-usages index — far faster than iterate-then-filter. Prefer #instances(C) over #nodes.ofConcept<C>().
• exact parameter on #instances excludes instances of sub-concepts (#instances<exact>(C)).
• MetaAdapterFactory is a rabbit-hole warning for Console tasks. If you feel tempted to use MetaAdapterFactory, hex feature IDs, generated StructureAspectDescriptor code, or hand-built SConcept / SContainmentLink objects while solving a Console command, stop and reframe the solution in surface syntax instead: #instances(Concept), node.property, node.childRole, replace with new(Concept), .forEach, or .refactor. MetaAdapterFactory belongs to low-level/generated implementation details, not the first-line solution for MPS Console work.
• Never hand-edit the console's .mps model. Use the editor or the MCP tool. The console lives in a temporary ConsoleModel_* model.
• Insertion and recall do not execute. mps_mcp_insert_console_command_from_json and mps_mcp_recall_console_command only place a command in the input; by default leave it for the user to run and tell them it is waiting. To execute it yourself, call mps_mcp_run_console_command (way #7) — it runs code with side effects, so do it deliberately and report what it did.
• Bulk node mutation: pick refactor vs forEach by whether you will run it. .refactor({~it => … }) (RefactorOperation) pops a modal confirmation dialog and applies nothing until a human approves it; .forEach({~it => … }) (collections VisitAllOperation) applies its closure immediately, in the console's own write command, with no dialog. So: when the user asks only to create / insert a command for them to run themselves (mps_mcp_insert_console_command_from_json and stop), prefer refactor — the dialog gives them a review-and-confirm step at the keyboard. When the user asks you to create and run it yourself (you will call mps_mcp_run_console_command), prefer forEach — refactor would return executed:true but stall on the dialog with no human present, leaving the model unchanged and the run a silent no-op.

Examples (surface syntax)

#models                                          // all editable models in the project
#modules<global>                                 // every module in the repository
#instances(ClassConcept)                         // fast: all ClassConcept instances in scope
#instances<exact>(BaseConcept)                    // exclude sub-concepts
#usages(aNode)                                    // direct references to a node
#print 2 + 2                                     // smart-print a value
#printNode someNode                              // print a node copy
#show #instances(Issue)                          // open the result in the usages view
#make #models<modules myModule>                  // make selected models
#reloadClasses                                   // reload generated classes

// migrate every TryStatement with a catch + long body to TryCatchStatement (from the MPS docs)
// `.forEach` applies immediately and headlessly; `.refactor` instead pops a confirmation dialog
#instances(TryStatement).where({~it => it.catchClause.isNotEmpty; }).forEach({~node => if (node.body.statement.size > 5) { node.replace with new(TryCatchStatement); } })

Related Skills

• mps-model-manipulation — the smodel / collections / closures operations (.where, .select, .ofConcept<C>, replace with new(C), :eq:) used in the bodies of console commands, with blocks, and refactor closures. The smodel query language layers on top of these.
• mps-node-editing — the JSON blueprint format that mps_mcp_insert_console_command_from_json consumes (shared with mps_mcp_insert_root_node_from_json).
• mps-aspect-intentions — a common host for with (…) { #instances(…)… } queries.
• mps-baselanguage — host BaseLanguage statements/expressions that fill BLCommand / BLExpression.
• mps-run-configurations — for running a main/test root node instead of console code.

Reference Index

• Open references/console-languages.md for the full console command-language reference — every # command grouped by language (base, ideCommands, internalCommands, scripts), aliases, what each prints, scopes, paste-as-nodeRef, and #exec scripts.
• Open references/smodel-query.md for the jetbrains.mps.lang.smodel.query language used in model code — the with statement, the six query expressions, scope parameters, the scope / exact / r/o+ query parameters, default-scope rules, and intention/behavior usage examples.
• Open references/mcp-insertion.md for mps_mcp_insert_console_command_from_json — the two accepted JSON shapes, validated working blueprints (BLExpression + query, statement arrays, interpreted commands), concept FQNs and language UUIDs, the "wrap expressions in BLExpression" gotcha, and dryRun validation.