MPS: Skill for Claude Code

Projectional Agent Toolkit – JetBrains MPS for Agents

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.

Entry point for working with JetBrains MPS (Meta Programming System) models, languages, generators, and the MPS MCP tools.

Read this together with AGENTS.md whenever the task involves MPS artifacts or MPS MCP tooling.

Critical Directives

⚠️ STOP — If you are reading raw .mps or .mpl XML files, you are way off track. MPS model files are opaque serialized XML: you cannot safely understand or edit them as plain text, and doing so will corrupt the model. Use mps_mcp_* tools instead. If they are not available, ask the user to start MPS and enable the MPS MCP server before continuing.

• Pass projectPath on every mps_mcp_* call, starting with the first one. The platform routes every call by resolving projectPath to an open project, so a call without it is rejected before dispatch ("Unable to determine the target project…") and costs a turn. Pass the open MPS project's base directory — a path at or inside it, never an ancestor such as the repository root. If you are not yet aware of that path, pass the session's current working directory (the one you already have — do not spend a turn discovering it); if that is rejected, take the path from the rejection message, which lists the open projects (Currently open projects: {...}). mps_mcp_list_open_projects reports the same value as mpsProjectBaseDirectory when it can run. Reuse that one path for every later call in the session.
• Empty Currently open projects: {"projects":[]} is the welcome screen, not a bad path. Retrying mps_mcp_* cannot succeed until some project is open. Load the mps-project-management companion skill from the same origin and open the project via CLI.
• Always prefer MPS MCP tools over hand-editing .mps / .mpl XML. Hand-edits silently corrupt model files.
• Before editing a language aspect, load its aspect skill. Changing typesystem rules → mps-aspect-typesystem (follow its Common-Path step 9: live-check the rules on a scratch sandbox); constraints → mps-aspect-constraints; behavior → mps-aspect-behavior; editor → mps-aspect-editor; generator → mps-aspect-generator; structure → mps-aspect-structure-concepts; any other aspect → mps-language-aspects-overview. The directives below do not replace the aspect skill.
• Preserve node IDs. Prefer mps_mcp_update_root_node_from_json or surgical edits (mps_mcp_update_node, …) over delete-and-reinsert. Deleting destroys persistent IDs and breaks incoming references.
• Copy-then-modify beats reconstruct-from-JSON. To create a node that closely resembles an existing one, duplicate it with mps_mcp_alter_nodes COPY_NODE and adjust the copy with mps_mcp_update_node, instead of printing the original and re-authoring it as a JSON blueprint. The copy is guaranteed structurally valid and needs no blueprint authoring at all.
• Generate deep blueprints, do not hand-nest them. If you write a blueprint as JSON rather than through mps_mcp_parse_java_and_insert, and it holds a BaseLanguage body or nests more than ~5 node levels, generate it with mps-node-editing's scripts/blueprint.py and pass the printed temp-file path. Load the mps-node-editing companion skill from the same origin to run it; its "Scripts" section is the contract. Hand-counted ]} runs are the usual cause of INVALID_JSON … unbalanced. Helper scripts and generated JSON go under $TMPDIR, never into the project or another directory of the user.
• Rebuild after compiled-aspect changes. After modifying typesystem, constraints, behavior, editor, or any other compiled aspect, rebuild the language module with mps_mcp_alter_nodes MAKE before validating with mps_mcp_check_root_node_problems on a consumer model. A MAKE answering runtimeReady: true is the reload; mps_mcp_reload_all compiles nothing (it reloads the classes already on disk) and adds nothing after it. Without a rebuild, cached compiled rules continue to fire — checking will report stale errors or miss new ones.
• The Structure-to-Aspect/Scaffold Prerequisite Chain (Ordering & Recovery). When editing a language's structure aspect (e.g., creating concepts/enums or modifying properties, children, or references via mps_mcp_alter_structure), you MUST adhere to the following strict sequence of cross-tool steps before invoking dependent tools (such as mps_mcp_get_concept_details or mps_mcp_scaffold_editor):
  1. Structure Edit: Modify the structure aspect (using mps_mcp_alter_structure).
  2. Clean Make/Rebuild: Run mps_mcp_alter_nodes with MAKE and rebuild=true targeting the language module (a model-scoped make can leave a never-before-deployed language's runtime hollow). Note: a plain mps_mcp_reload_all alone is not sufficient because the generated structure aspect descriptor classes on disk must be regenerated before the ClassLoader reloads them.
  3. Verify Descriptors: Retrieve the compiled concept details using mps_mcp_get_concept_details and verify that the descriptorStatus is not "hollow" and no warnings exist.
  4. Scaffold / Aspect Editing: Once the descriptors are verified as compiled and active, proceed to scaffold the editor (mps_mcp_scaffold_editor) or define other aspects (behavior, constraints, typesystem, generator, etc.). Failing to follow this ordering results in stale or hollow descriptors where dependent tools silently see empty properties, children, or references. A MAKE writes only generated output (source_gen/classes_gen), changes no model, and is allowed in a task that forbids model edits. Tools that need the runtime now answer LANGUAGE_NOT_BUILT for a concept of an unbuilt language, with details.languageBuild.recovery naming the exact MAKE call to run. Shortcut: mps_mcp_alter_structure CREATE_CONCEPTS with make: true already does steps 2–3 — it clean-rebuilds, verifies every created descriptor against the runtime, and auto-recovers a never-deployed language (one module-scoped rebuild, recoveryStage: "module-rebuild"). Trust its makeStatus; run the manual chain only for structure edits made through tools that do not make (UPDATE_*/RENAME_* operations, mps_mcp_update_node).
• Surgical edits over full-root rewrites. When a single child changes, prefer mps_mcp_update_node over re-running mps_mcp_update_root_node_from_json on the whole root.
• Never simulate the typesystem. To decide whether a type fits, what a slot requires, what an operator returns, or why a node has a type, call mps_mcp_query_types (IS_SUBTYPE, SUPERTYPES, COMMON_SUPERTYPE, COERCE, OPERATION_TYPE, EXPLAIN_TYPE) or mps_mcp_query_nodes (GET_TYPE, GET_EXPECTED_TYPE). Print a SubtypingRule / InferenceRule root only to change it, or to pick the sibling you COPY_NODE — not to predict what the engine will answer: even while authoring, ask the engine for the rest, including what your change does to operators and joins (OPERATION_TYPE, COMMON_SUPERTYPE). If an engine answer surprises you (null, false), ask EXPLAIN_TYPE; do not open the rule. See references/analysis-tools/type-queries.md for the operation table and caveats.
• Never simulate the dataflow engine. To see the program a dataflow builder emits, which builder emitted an instruction, why a node is unreachable, which writes reach a read or which reads a write feeds, call mps_mcp_query_dataflow (PRINT_PROGRAM, REACHING_WRITES, REACHING_READS); do not print builder roots to predict the program, and do not hand-write a console probe of jetbrains.mps.lang.dataFlow. See references/analysis-tools/dataflow-queries.md.
• Check the IDE log when the envelope and the effect disagree. When a tool reports success but the effect is missing, or a skill says an error "surfaces only in idea.log", call mps_mcp_read_ide_log with sinceMinutes covering the call window and minLevel="WARN" (no path needed, works for standalone MPS); references/ide-log.md has the recipe and the fallback for older servers.
• Validate frequently. A successful insertion ("ok": true) does not mean the AST is semantically valid — always follow with mps_mcp_check_root_node_problems. Read warnings and details.uncheckedSubtrees, not just the data verdict: commented-out code and other IDontApplyTypesystemRules / ISkipConstraintsChecking subtrees are not checked, so a clean verdict over them proves nothing — ask IS_SUBTYPE. A problem may carry rules: [{rule, ruleReference, statement}]: rules[0].rule names the reporting rule — cite it instead of guessing; print ruleReference only to change that rule.