MPS Node Editing

The core workflow for mutating MPS nodes through MCP tools. JSON blueprints describe the node hierarchy you want; the tools resolve concepts, references, and used languages on insert.

Critical Directives

• Always use the fully qualified concept name in the concept field — it is unambiguous and does not require a conceptReference.
• Resolve before editing — call mps_mcp_get_current_editor_root_node (for the user's focus) or mps_mcp_search_root_node_by_name (by name) to lock onto the target. Don't guess refs.
• Prefer surgical edits — mps_mcp_update_node (ADD/CHILD or SET/CHILD) preserves persistent IDs. mps_mcp_update_root_node_from_json rewrites the entire root and is wasteful when only one subtree changed.
• Don't delete-and-reinsert to make a small change — deletion destroys persistent IDs and breaks incoming references.
• Cloning an existing node? Use mps_mcp_alter_nodes COPY_NODE, not a JSON blueprint. It clones the subtree natively — correct concept, properties, refs, nested structure — as the next sibling (multi-child role) or new root, then tweak with mps_mcp_update_node. Reserve JSON blueprints for nodes with no close match to copy from.
• Validate frequently — call mps_mcp_check_root_node_problems immediately after inserting or modifying a complex node. "ok": true from insert does not mean the AST is semantically valid.

mps_mcp_update_node — Unified Node-Mutation Tool

All child, property, and reference operations on existing nodes go through mps_mcp_update_node. The operation is selected via operation (ADD/SET/DELETE) × kind (CHILD/PROPERTY/REFERENCE).

ADD × PROPERTY and ADD × REFERENCE are not valid combinations and return an error envelope.

mps_mcp_update_node (PROPERTY / REFERENCE / CHILD) and mps_mcp_alter_nodes MOVE_CHILD / MOVE_NODE_TO_PARENT / COPY_NODE also work on nodes inside the current MPS Console input command — pass the node's normal persistent reference; no extra parameter is needed. The node must be inside the current unexecuted console input (not history/stale). MOVE_NODE_TO_PARENT only relocates a node within the current console command — moving a node between the console and a project model, or making a console node a root, is refused. Edits to console nodes skip disk-persistence and refresh the console's imports instead. Nodes outside the selected project are rejected as before.

childJson accepts either an inline JSON string (max 4 KB) or an absolute path to a file containing the JSON blueprint. Use the file form for large blueprints to avoid MCP-transport truncation.

Prerequisites

• Load the mps-language-analysis skill if you do not yet know what concepts the model uses.
• Resolve the target node (unless creating a brand-new root):
  • mps_mcp_get_current_editor_root_node for the user's focus.
  • mps_mcp_search_root_node_by_name for a known name.
• Resolve required languages and concepts:
  • Check used languages of the current model via mps_mcp_get_project_structure.
  • Get concept details using mps_mcp_get_concept_details for specific languages.
  • Use mps_mcp_search_concepts for discovery.

Common Workflow

1. Identify the target node (existing) or parent model (new root).
2. Choose the right tool: mps_mcp_create_root_node / mps_mcp_insert_root_node_from_json for new roots; mps_mcp_update_node (ADD/SET/DELETE × CHILD/PROPERTY/REFERENCE) for surgical edits; mps_mcp_update_root_node_from_json only for full-root rewrites.
3. Author the JSON following the unified blueprint format.
4. Insert with dryRun: true first if the blueprint is large. Check the response: an empty warnings array means staging was clean; a non-empty list means the production write will produce dynamic (unresolved) references for the listed targets — resolve those first or expect broken refs.
5. Validate with mps_mcp_check_root_node_problems. Reported problems may carry a quickFixes array; apply one with mps_mcp_apply_intention, or pass autoApplyQuickFixes=true for one-shot repair of the auto-applicable ones.
6. Repair broken refs with mps_mcp_alter_nodes FIX_REFERENCES if validation surfaces resolvable-but-unresolved targets.

Related Skills

• mps-aspect-structure-concepts — defines what concepts exist and what roles they expose.
• mps-baselanguage — when the nodes you edit are BaseLanguage / Java.
• mps-quotations — embedding inline node literals inside model code.
• mps-language-analysis — exploring an unfamiliar language before editing.
• mps-model-manipulation — when the edit also requires navigating the tree from model code (.ancestor<C>, .descendants<C>, siblings, containingRoot).

JSON Input — File-Path Semantics

The tools that accept a node JSON blueprint (mps_mcp_update_node for ADD/SET × CHILD, mps_mcp_insert_root_node_from_json, mps_mcp_update_root_node_from_json) all use the same childJson / json parameter convention:

• The parameter can be either a JSON string (max 4 KB) or an absolute path to a local file containing the JSON.
• Files may contain either a raw node blueprint or the full MCP response envelope produced by mps_mcp_print_node; in the latter case the data field is used.
• Ordinary input files are never deleted. Only temporary JSON files created by this toolset may be cleaned up after reading (and only when dryRun=false).
• Very large JSON inputs may be truncated by the MCP transport before the tool reads them. If that happens, insert a smaller blueprint first and add children in follow-up calls with mps_mcp_update_node (ADD/CHILD or SET/CHILD), or pass the JSON as a file path instead of an inline string. See references/staged-construction.md for the recommended pattern.

Reference Index

• Open references/json-format.md when you need the unified JSON blueprint shape — concept/properties/children/references layout, optional-section rules, and reference-resolution semantics (r:... vs name auto-resolution).
• Open references/staged-construction.md when the subtree is large (>~4 KB) or its child refs are needed for later edits — the skeleton → validate → incremental-fill → targeted-update → cleanup pattern.
• Open references/troubleshooting.md when an insert call fails with JsonElement.getAsString() errors or when the JSON shape diverges from the user's textual notation.