Mps Project Management

Closing a project

Use mps_mcp_close_project to close the project selected by the host's projectPath. Opening still has no MCP tool — after the last project closes, MPS typically returns to the Welcome screen and you must reopen via CLI (the workflow above).

• Select the target project. The path must be at or inside that open project, never an ancestor such as the repository root. When several projects are open, call mps_mcp_list_open_projects first and pass the intended project's mpsProjectBaseDirectory as projectPath.
• A normal close may show dialogs. It saves documents and runs can-close checks. Save / confirmation dialogs block the call until they are dismissed.
• Do not wait past 20 seconds. If the tool returns ok:false with code: MODAL_BLOCKED, a modal dialog is likely open in MPS (Save, confirmation, Find Usages, Search, etc.). Ask the user to close that dialog manually, then retry. Do not assume the project closed.
• Prefer force=false. Pass force=true only after a previous close timed out or was cancelled on a confirmation dialog. Force-close skips the save/can-close dialogs this close would show (unsaved editor changes are discarded) and does not wait for an already-open unrelated modal.
• Shut down MPS with shutdownWithLastProject=true. When asking MPS to close a project, it can also be instructed in the same MCP call to shut down, if MPS sees no other open projects (it checks for open projects itself, no need to check yourself). When MPS is displaying the welcome screen (no projects are open), it cannot be shut down via MCP. A modal confirmation dialog may (if configured) prevent MPS from shutting down.

1. If several projects are open, list them and pass the intended mpsProjectBaseDirectory as projectPath.
2. Call mps_mcp_close_project with the default force=false.
3. On {ok:true, data.closed:true}, stop. Closing the last project is expected to leave the Welcome screen.
4. If the close was cancelled (the project remains open): ask the user to complete the dialog, or retry with force=true.
5. If code: MODAL_BLOCKED: ask the user to close the blocking dialog, then retry. Use force=true only to skip save/confirmation dialogs that this close itself would show.

Creating a new empty project

There is no MCP tool to create a new MPS project. To create a new empty project headlessly, write the minimal project descriptor files directly on disk: create the project root directory containing .mps/modules.xml (empty MPSProject), .mps/.gitignore, and .mps/migration.xml. Then open the directory in MPS via the CLI activation workflow above. migration.xml is the one file whose content is MPS-version-specific: generate it from the MPS installation that will open the project — never hardcode migration ids from memory and never reuse a file written for another MPS version, or the modal Migration Assistant blocks every mps_mcp_* call on first open.

See references/create-empty-project.md for file templates and instructions.

Scripts

scripts/new_project_migration_xml.py — builds the .mps/migration.xml of a new empty project from the MPS that will open it (install directory, macOS .app, or source checkout), offline: no running MPS and no existing project to copy from. Needed for every MPS other than 2026.2, whose file references/create-empty-project.md gives verbatim.

python3 scripts/new_project_migration_xml.py "/Applications/MPS 2025.3.app" /path/to/new/project
baseline 253 from MPS-253.29346.537 (/Applications/MPS 2025.3.app/Contents/Resources/build.txt)
         243 jetbrains.mps.ide.mpsmigration.v_2024_3.LangResourceImport4Migration -
<?xml version="1.0" encoding="UTF-8"?>
...

Related Skills

• mps-mcp-workflow — once a project is open, this is the entry point for model and language work.
• mps-run-configurations — running DSL roots inside an already-open project, not launching MPS itself.

Reference Index

• Open references/why-mcp-cannot-open.md when diagnosing welcome-screen MCP rejections.
• Open references/detect-source-vs-standalone.md to classify the running process.
• Open references/open-via-cli.md for the activation protocol (what to keep, what to strip, success criteria).
• Open references/examples-macos.md, references/examples-linux.md, or references/examples-windows.md for copy-paste commands.
• Open references/create-empty-project.md for file templates and instructions on creating a new empty MPS project.
• Open references/derive-migration-xml.md when that project will be opened by an MPS other than 2026.2, to generate .mps/migration.xml for that release.