---
name: mps-console
description: >-
  Run or generate MPS Console code and `jetbrains.mps.lang.smodel.query` queries in MPS intentions, behavior, actions, generators, and BaseLanguage. Covers console commands, result printers, IDE operations, scripts, scoped node/model/module queries, and inserting, reading, recalling, or running commands through MPS MCP tools.
type: reference
---

# MPS Console and the smodel query language

## Loading companion skills

Companion names in this skill are lazy dependencies: load only those relevant to the current task. If this skill came from an MCP server, use the host's skill loader to resolve the companion's unique discovered entry URI on the same host-assigned originating server. If the host has no server-backed skill loader, stop and report that limitation; do not silently fall back to a filesystem copy. If this skill came from a filesystem catalog, load the named sibling from that same catalog at `<skills-root>/<skill-name>/SKILL.md`, even if remote skill loaders are also available. Do not invent a tool name or server endpoint.

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`, which also has a generator script for a query with `.where(…)` / `.select(…)` closures.
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 list each command's printed output as a `kind:response` entry right after it, with a one-line `preview`; see "Reading a command's output" below for the full text and for the node references inside it. 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 as "Reading a command's output" below describes, 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`):

| Shape | Concept | What it is |
|---|---|---|
| BaseLanguage statements | `BLCommand` (alias `{`) — `body: StatementList` | a `{ … }` block of imperative statements; the value of a trailing expression statement is printed |
| BaseLanguage expression | `BLExpression` — `expression: Expression` | one expression; if non-void its value is printed (as text / AST / interactive response) |
| Interpreted command | `InterpretedCommand` subtypes | non-generated commands: `#stat`, `#showGenPlan`, `#showBrokenRefs`, `#reloadClasses`, `?` (help) |

**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 **`Expression`s**, not `Command`s. 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.

## Reading a command's output

`mps_mcp_run_console_command` does not return the output, and execution is asynchronous. To read it:

1. Before running, note the `index` of the last history entry (`limit = 1`); `index` counts the whole history, so your command is the `kind:command` with a higher `index`, even when it repeats an earlier command. After running, call `mps_mcp_get_console_history(includeResponses = true, limit = 2)`. The command is finished when the last entry is a `kind:response` and the entry before it is your `kind:command`. If your `kind:command` is the last entry, it is still running, or it printed nothing: a command that prints nothing gets no response entry. If your command is not listed yet, it has not started. Call again a few times, then stop waiting.
2. The response entry's `preview` is the printed text with whitespace and line breaks collapsed to single spaces, cut at 200 characters. It is omitted when the text is empty or cannot be rendered, and for long responses (over 100 items, where each printed value and each line break counts). Read `previewComplete` next to it:
   - `true`: the preview **is** the exact printed text, with only the Console's leading and trailing padding removed. This is the usual case for a count (`3 nodes`) or a short one-line value list. Report it as it is; do not print the node again.
   - `false` (the preview was cut and ends in `…`, or it was collapsed from several lines), or no `preview` at all: call `mps_mcp_print_node(nodeReference = <the response entry's reference>, format = "PLAIN TEXT")` for the exact full text.
3. For node references in the output, print the same `reference` with `format = "JSON"` and `deep = true`. Each printed node is an `item` child holding a `NodeReferencePresentation`. The `targetReference` of its `target` reference is the real node, which you can pass to any other tool.

The console prints a value according to its type, and an agent can only get back what was printed:

| Value | Printed text | `Response` node children (`item`) |
|---|---|---|
| a non-empty sequence or list of nodes, references, models, or modules (`#instances(C)`, `.where(…)`, `.toList`, `#models`) | only a count, e.g. `3 nodes` or `12 models`. In the IDE the count links to the usages view. | one `NodeResponseItem` → `NodeWithClosure`, whose `text` is the count. **The items cannot be recovered.** |
| an empty sequence of any of these | `empty sequence` | one `TextResponseItem` |
| a single node (`.first`, `#print node`) | the node's presentation, usually its name | `NodeResponseItem` → `NodeReferencePresentation`, `target` = the node |
| anything else: a string, a number, a sequence of strings | the value's `toString()`, e.g. `[Flour, Sugar, Egg]` | one `TextResponseItem`, whose `text` is that string |

So shape the query for what you need back:

- **Values:** select them before printing: `#instances(Ingredient).select({~it => it.name; })` prints one list of the names, such as `[Flour, Sugar, Egg]`.
- **Node references:** print each node: `#instances(Ingredient).forEach({~it => #print it; })` gives one `NodeReferencePresentation` per node, read with step 3.
- **Not** `.forEach({~it => #print it.name; })` for values. The items print separated only by spaces, so a name containing a space cannot be told apart from two names.

## 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.