Mps MCP Workflow

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

Tool name note: MPS MCP tools are named with a mps_mcp_ prefix (e.g. mps_mcp_query_nodes, mps_mcp_alter_nodes, mps_mcp_get_concept_details). Your MCP client wraps these with a server-specific prefix (e.g. mcp__mps-mcp-server__<env>___), which varies by environment. Match tools by the stable mps_mcp_* suffix.

Load each tool's schema before its first call (ToolSearch select: when the host defers schemas). The keys are not guessable: nodeReference, conceptRefs/languageRefs, searchTexts, parameters.code / insert.modelRef.

Which project the tools act on (subdirectory & multi-project checkouts). The mps_mcp_* tools operate on the MPS project currently open in the running MPS instance. That project often lives in a subdirectory of your repository (e.g. <repo>/tools/BigProject, as in mbeddr or MPS-extensions), and one checkout may even hold several MPS projects. Supply that project's mpsProjectBaseDirectory — the folder MPS actually opened, i.e. a path at or inside it, not the repository root — as projectPath on every call, per the Critical Directive above. The first-call CWD probe in that directive still applies when the path is unknown, even if CWD is the repository root. This is the opposite of mps_mcp_initialize_project_for_agents, whose targetDirectory is the repository / workspace root (where .agents/, .claude/, AGENTS.md, and CLAUDE.md belong), which may be an ancestor of the MPS project directory.

Multi-project repository rules. All open MPS projects share the same module repository. Write targets — models, modules, root nodes, and nodes being mutated — must belong to the project selected by projectPath; tools refuse writes to another open project's elements. Read/reference/dependency targets may come from another open MPS project when they are explicitly named or imported: model/module dependencies, model used languages/devkits, node concepts, and reference targets can point across projects, and the foreign elements are treated like read-only library/stub elements. Returned JSON for an element from another open project includes containingProject: { name, mpsProjectBaseDirectory } and editableFromCurrentProject: false; nested references use prefixes such as conceptContainingProject, targetContainingProject, or typeContainingProject. These markers appear only for elements owned by another open project — their absence does not imply an element is editable (a read-only library/stub in the current project carries readOnly: true but no containingProject), so decide editability from readOnly together with these markers.

When in doubt, ask which project. When several MPS projects are open under one repository / VCS root, the mps_mcp_* tools accept any valid project path and act relative to that project. Same-name resolution prefers the selected project's own elements before falling back to the shared repository, but an explicit reference may still resolve to another open project. If the intended project is not obvious from the user's request or the current editor focus (mps_mcp_get_current_editor_root_node), do not guess — show the mps_mcp_list_open_projects entries and ask the user which project the query or change should run against.

Companion Skills

The MPS catalog contains companion skills for focused task families. Load whichever ones apply to your current task, following the origin rules above.

Installing / refreshing the catalog. These mps-* skills and the project's AGENTS.md/CLAUDE.md are installed and refreshed by the mps_mcp_initialize_project_for_agents MCP tool. It installs into a targetDirectory — normally your repository / workspace root (the folder containing .git), which may be an ancestor of the MPS project directory when the project sits in a subdirectory; leave targetDirectory empty to let the tool derive that root from the open project's enclosing VCS folder, while still passing the project's base directory as projectPath like every other mps_mcp_* call (targetDirectory and projectPath are different arguments — an ancestor is valid for the first and rejected for the second). If no mps-* skills exist yet, the project has not been initialized for agents — tell the user and offer to run it.

A successful install writes MPS_MCP_SKILL_VERSION.txt into both .agents/skills/ and .claude/skills/; compare its build with top-level mpsBuild from mps_mcp_list_open_projects (never call the initializer to learn the version). The installed AGENTS.md states the staleness rules.

If the catalog looks stale or incomplete, offer to refresh it (with approval): delete every mps-* skill folder from .agents/skills/ and .claude/skills/ — keeping repository-local skills (such as bugfix-workflow and *-dsl skills) — re-run the tool, then carefully merge its returned agentsFileText into AGENTS.md/CLAUDE.md, preserving project-specific sections. See that tool's description for the exact refresh contract.