MPS Language Aspects — Overview

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.

An MPS language is a collection of aspects, each a separate model inside the language module. Together they define syntax, semantics, UI, and output. Edit each aspect through its own language (its DSL). This skill is the router; each aspect names a dedicated companion skill.

Critical Directives

• Always prefer MPS MCP tools over hand-editing .mps XML. Hand edits can silently corrupt model files.
• Keep aspect rules thin and declarative — push logic into behavior methods, then call them from any aspect.
• When something in a consumer is wrong, re-check the root cause on the language side (structure / generator / typesystem) before patching generated Java.
• Choose a modularity strategy before authoring when this language must relate to others — reference, extend, embed, or adapt them. The kind you pick (referencing / extension / reuse / embedding) changes how you use structure, constraints, typesystem, and generator. See mps-language-modularity.

Aspects and Where to Find Detailed Guidance

Aspect IDs are case-sensitive and create models named <langModule>.<aspectId> with no @ suffix. Stereotypes (@generator, @genplan, @tests, @descriptor) are a separate mechanism for non-aspect models. Authoritative table with usage notes and pitfalls: aspect-model-stereotypes.md.

Additional aspects exist (Find Usages, Refactorings, Scopes Provider, Plugin). They follow the same "per-concept rule root + body" pattern — load an applicable companion skill or consult the MPS user guide when needed.

Generation Plans (cross-cutting, not an aspect of a single language) are covered by mps-aspect-generation-plan. Use when you need to control generator ordering, enable cross-model reference resolution with checkpoints, fork generation into parallel branches, or conditionally contribute plans via PlanContribution.

Typical Authoring Order

1. Structure — concepts, properties, children, references, inheritance.
2. Editor — notation, cell layouts, projections; iterate alongside sample models.
3. Constraints — property validators, reference scopes, placement rules.
4. Behavior — concept methods/constructors; callable from any aspect.
5. Typesystem & checking — types, subtyping, semantic errors with quick fixes.
6. Intentions — alt-enter refactorings and shortcuts.
7. Generator — transform to a target language (often BaseLanguage).
8. TextGen — only if the target is plain text the language itself emits.
9. Accessories / runtime / dependencies — wire into the .mpl, ensure consumers can find everything.

Most iteration is circular: structure ↔ editor ↔ constraints ↔ typesystem.

Cross-Aspect Calls

• Any aspect body can call behavior methods on nodes (node.m(...)).
• Typesystem rules call quick-fix intentions via error ... fix { ... } or by referencing QuickFix roots.
• Generator templates call behavior methods for nontrivial logic and use mapping labels for cross-template references.
• Constraints may call behavior methods for reusable checks.
• Editors may call behavior methods in query/if/cell-model blocks.

Keep logic in behavior methods; keep aspect rules thin and declarative.

MCP Tools You'll Use Often

• Exploration: mps_mcp_get_project_structure, mps_mcp_search_concepts, mps_mcp_get_concept_details, mps_mcp_print_node.
• Authoring: mps_mcp_create_root_node, mps_mcp_insert_root_node_from_json, mps_mcp_update_node, mps_mcp_parse_java_and_insert.
• Structure-specific: mps_mcp_alter_structure (CREATE_CONCEPTS, CREATE_ENUM, UPDATE_CONCEPT_*), mps_mcp_query_structure (inheritance/aspect queries); example nodes of a concept via mps_mcp_query_nodes (FIND_INSTANCES).
• Modules/models: mps_mcp_create_module, mps_mcp_create_model, mps_mcp_model_dependency, mps_mcp_model_used_language, mps_mcp_module_dependency.
• Validation: mps_mcp_check_root_node_problems, language/module build via IDE MCP.

Dependencies and Rebuilds

After adding/changing:

• Concepts (structure) — downstream aspects' references by concept may break; validate them. Rebuild language.
• Behavior method signatures — all callers (generator, typesystem, constraints, intentions, editor queries) must be re-validated. Rebuild language.
• Generator templates — rebuild generator module (it's separate from the language module).
• Runtime solutions — rebuild the runtime solution; consumers pick up changes on next regeneration or reload.
• After large changes: rebuild the language module (MAKE, rebuild:true); runtimeReady:true means the runtime registry is fresh.

Validation Flow

1. mps_mcp_check_root_node_problems on edited roots / aspect models, or on the language module to sweep every aspect (and its generator) in one call — catches concept-level problems.
2. Build the language module (mps_mcp_alter_nodes MAKE, rebuild:true; runtimeReady:true means MPS has reloaded it) — catches compile errors in generated descriptors.
3. Regenerate a sample model — catches generator/textgen issues.
4. Ask the engine on a sandbox root (mps_mcp_check_root_node_problems, mps_mcp_query_nodes GET_TYPE, mps_mcp_query_types IS_SUBTYPE / EXPLAIN_TYPE) instead of inspecting it in the MPS UI — catches typing and checking issues; mps-aspect-typesystem Common-Path step 9 has the scratch-model recipe. Editor / usability issues still need a look in MPS.

When something in a consumer is wrong, always re-check the root cause on the language side (structure / generator / typesystem) before patching generated Java.