CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

mps-console

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.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

—

The risk profile of this skill

SKILL.md
Quality
Evals
Security

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):

ShapeConceptWhat it is
BaseLanguage statementsBLCommand (alias {) — body: StatementLista { … } block of imperative statements; the value of a trailing expression statement is printed
BaseLanguage expressionBLExpression — expression: Expressionone expression; if non-void its value is printed (as text / AST / interactive response)
Interpreted commandInterpretedCommand subtypesnon-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 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.

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:

ValuePrinted textResponse 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 theseempty sequenceone TextResponseItem
a single node (.first, #print node)the node's presentation, usually its nameNodeResponseItem → NodeReferencePresentation, target = the node
anything else: a string, a number, a sequence of stringsthe 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 operations (.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-collections-and-closures — the collections / closures operations (.where, .select, .translate, closure literals) that filter and transform query results.
  • 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.
Repository

JetBrains/MPS

Path

.agents/skills/mps-console/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.