MPS: Skill for Claude Code

Projectional Agent Toolkit – JetBrains MPS for Agents

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.

• Always prefer MPS MCP tools over hand-editing .mps / .mpl XML. Hand-edits silently corrupt model files.
• 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.
• Reload after compiled-aspect changes. After modifying typesystem, constraints, behavior, editor, or any other compiled aspect, call mps_mcp_reload_all (or rebuild the language module via mps_mcp_alter_nodes MAKE) before validating with mps_mcp_check_root_node_problems on a consumer model. Without a reload, 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. 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.
• Validate frequently. A successful insertion ("ok": true) does not mean the AST is semantically valid — always follow with mps_mcp_check_root_node_problems.