From ebb88791bab524618984de71d74c6a74aeb311aa Mon Sep 17 00:00:00 2001 From: Velizar Seleznev Date: Tue, 4 Aug 2026 12:21:24 +0200 Subject: [PATCH 1/2] docs: clarify MCP clients and local models --- mcp/antigravity.mdx | 183 +++++++++++++++++++++---------------------- mcp/local-models.mdx | 51 +++++++++--- mcp/opencode.mdx | 54 ++++++++++--- mcp/overview.mdx | 5 +- mcp/setup.mdx | 102 +++++++++++++++++++++--- 5 files changed, 270 insertions(+), 125 deletions(-) diff --git a/mcp/antigravity.mdx b/mcp/antigravity.mdx index d8e9903..eec2715 100644 --- a/mcp/antigravity.mdx +++ b/mcp/antigravity.mdx @@ -1,142 +1,141 @@ --- title: "Build Games in Antigravity with Summer Engine MCP" -description: "Connect Summer Engine's MCP server to Antigravity and build games with Google's AI-powered IDE driving your engine." +description: "Set up Summer Engine in Antigravity's current native MCP and Agent Skills directories without changing your model." icon: "rocket" --- -{/* Do not reintroduce a hardcoded MCP tool count here. The tool list grows every release and a baked-in number has already gone stale twice. */} - ## Summer Engine in Antigravity -Antigravity is Google's AI-powered IDE that supports MCP (Model Context Protocol). With Summer Engine's integration, Antigravity's AI can control your game engine: add nodes to scenes, set properties, import assets, run the game, and debug, all from within your coding workflow. - -This guide covers the configuration. Setup takes about a minute. +Antigravity is the MCP client. Its selected Google or third-party model is a +separate setting; Summer setup does not change that model or provider. ## Prerequisites -- **Antigravity**: Google's AI-powered IDE -- **Node.js**: For running the MCP server (Node 18+) -- **Summer Engine**: Installed and running with your project open +- **Antigravity** +- **Node.js 18+** +- **A Summer Engine project** open in Summer Engine -## Configuration +## One-command project setup -Antigravity uses the VS Code MCP config format. The config file is: +Update the terminal client first, then open a terminal in the project: -- **Project-level:** `.vscode/mcp.json` in your project root -- **Global:** Use the Antigravity CLI (`antigravity --add-mcp`) if available +```bash +agy update +``` - -**Config format.** Antigravity uses `servers` (not `mcpServers`). The structure matches VS Code's MCP configuration. - +Open a terminal in the project and run: -### Step 1: Create or Edit the Config File +```bash +npx -y summer-engine@latest setup antigravity --yes --force --project "$PWD" +``` -Create `.vscode/mcp.json` in your project root. If the file already exists (e.g., for other MCP servers), add Summer Engine to the existing `servers` object. +This creates or merges: -### Step 2: Add Summer Engine +- `.agents/mcp_config.json` with the `summer-engine` MCP server +- `.agents/skills//SKILL.md` with recommended Summer guidance - +It preserves other MCP servers and unrelated JSON keys. The generated MCP +command is bound to the absolute project path, so it does not guess when more +than one Summer editor is open. -```json New file (.vscode/mcp.json) -{ - "servers": { - "summer-engine": { - "command": "npx", - "args": ["summer-engine", "mcp"] - } - } -} -``` + +Current Antigravity uses `.agents/mcp_config.json` with a top-level +`mcpServers` object. Older instructions that use `.vscode/mcp.json` and +`servers` describe a legacy compatibility path. + + +For a global setup, run without `--project` and add `--scope user`. The +global files live under `~/.gemini/config/mcp_config.json` and +`~/.gemini/config/skills/`. -```json Adding to existing servers +## Manual configuration + +```json .agents/mcp_config.json { - "servers": { - "other-server": { ... }, + "mcpServers": { "summer-engine": { "command": "npx", - "args": ["summer-engine", "mcp"] + "args": [ + "-y", + "summer-engine@latest", + "mcp", + "--project", + "/absolute/path/to/your/project" + ] } } } ``` - - -### Step 3: Restart Antigravity - -Close and reopen Antigravity so it loads the new MCP config. The Summer Engine MCP server starts when Antigravity starts; it connects to the engine on the first tool call. - -### Step 4: Verify - -Check Antigravity's MCP or AI settings to confirm "summer-engine" appears and its tools are listed. Then try a prompt: +## Reload and verify -- "Use Summer Engine to add a MeshInstance3D with a BoxMesh to the scene" +In the desktop app, open **Settings > Customizations > MCP Servers**. In the +terminal client, start `agy` from the configured project and run `/mcp`. -If the node appears in Summer Engine, the setup is working. +1. Refresh or restart `summer-engine` and inspect its connection status. +2. Confirm the host itself lists the Summer tools; `doctor` only proves the + server can register them. +3. Keep MCP tools in **Ask** mode for the first test. +4. Start a fresh conversation in the configured project and paste: -## Using Summer Engine with Antigravity +```text +Use the summer-engine MCP server. Call summer_get_agent_playbook and read its +result. Then call summer_get_project_context and summer_get_scene_tree. Report +the exact project and scene you found. Do not change anything. If a call fails, +quote the error and stop. +``` -Once configured, the AI can use Summer Engine's tools when you ask for game-related changes. Example prompts: +Only proceed to mutations when the model discovers the server, calls a tool, +consumes its result, and reports the correct project identity. -- "Add a Camera3D and DirectionalLight3D to the scene root" -- "Get the scene tree from Summer Engine" -- "Import this model and add it to the World node: [URL]" -- "Run the game and capture a screenshot" -- "Set the project's main scene to res://main.tscn" + +In our `agy` 1.1.10 interactive smoke, the project-scoped server called and +consumed the playbook, project context, and scene tree, then added and saved a +node, read it back, removed and saved it, and confirmed the clean final tree. + - -**Engine must be running.** Antigravity's AI talks to Summer Engine over localhost. Open your project in the engine first, or run `npx summer-engine run` from the project directory. - + +Do not use `agy -p` (headless print mode) as the MCP readiness check in that +build. It rejected the same working project server with +`tool ... is not enabled for server summer-engine`, while a normal interactive +`agy` session succeeded. If that error appears under `-p`, start `agy` normally +in the configured project, run `/mcp`, and test in a fresh conversation. Stop +before mutations only if the normal interactive session also rejects the call. + ## Troubleshooting -### "Summer Engine is not running" +### Server does not appear -Start Summer Engine and open your project. The MCP server connects to the engine's local API on port 6550. The engine writes a token to `~/.summer/api-token` when it starts. +- Confirm the opened project contains `.agents/mcp_config.json`. +- Open **Customizations > MCP Servers**, refresh, and inspect the connection + log instead of repeatedly restarting. +- Run `npx -y summer-engine@latest doctor --json` in the project. -### MCP server not appearing +### Summer Engine is not running -- **Config path:** Verify `.vscode/mcp.json` is in your project root (the folder you opened in Antigravity) -- **JSON validity:** Ensure no trailing commas, proper quotes, and valid JSON structure -- **Restart:** Fully quit and reopen Antigravity +Open the same project in Summer Engine. The MCP process discovers the matching +local editor instance on its first tool call. -### Tools return errors +### Tools are listed but the model does not call them -See the [Tools Reference](/mcp/tools-reference) for parameter formats. Common issues: wrong node path format (`./World/Player`), invalid property values (use engine string format like `"Vector3(0, 10, 0)"`), or the game running when scene edits are attempted (stop it first with `summer_stop`). +Start a fresh conversation, use a model trained for multi-turn tool calling, +give it at least 64k context, and require the read-only playbook/context test +above. Tool visibility alone does not prove the model can consume tool results. -## Next Steps +## Next steps - - Every MCP tool with parameters and examples + + Client/provider choices and supported setup targets - - How an AI builds a full game using MCP + + MCP tools and parameter formats - - Architecture, prerequisites, and other IDEs + + Use LM Studio, OpenCode, Ollama, or Goose with the same MCP server - - summer install, run, create, and more + + Move from read-only verification to a real project - ---- - -Need help or have questions? Reach out to our founders at [founders@summerengine.com](mailto:founders@summerengine.com) or join our community on [Discord](https://discord.gg/yUpgtxnZky) for fast responses. diff --git a/mcp/local-models.mdx b/mcp/local-models.mdx index 74b1e3c..fc1b3df 100644 --- a/mcp/local-models.mdx +++ b/mcp/local-models.mdx @@ -8,7 +8,16 @@ icon: "microchip" You don't need an AI subscription to build games in Summer Engine. Any local model that handles tool calling can drive the engine through MCP: add nodes, set properties, search and import assets, run the game, and debug. Engine control and asset search are free; cloud generation (3D models, images, audio) uses credits. -This page covers the three setups that actually work in 2026. +First choose an MCP client. Then choose the model runtime/provider. They are +independent layers: + +| MCP client | Model runtime/provider | Setup status | +|---|---|---| +| LM Studio chat | LM Studio | Direct CLI-managed MCP setup | +| OpenCode | Any existing provider | CLI-managed, provider-neutral MCP setup | +| OpenCode | LM Studio | Explicit combined recipe | +| OpenCode or Kilo Code | Ollama | MCP setup is managed; provider setup remains client-owned | +| Goose | Ollama or another provider | Manual MCP extension setup | ## Prerequisites @@ -16,23 +25,41 @@ This page covers the three setups that actually work in 2026. - **Node.js**: For running the MCP server (Node 18+) - **Summer Engine**: Installed and running with your project open -## Option 1: LM Studio (easiest) +## Option 1: LM Studio directly + +LM Studio is both the model runtime and an MCP host. One terminal command writes +the integration; the actual model chat and tool calls then stay inside LM Studio. -LM Studio is both the model runtime and an MCP host — one app, no terminal. +LM Studio Chat cannot run the installer for you. Do not paste the coding-agent +setup prompt into the model and expect it to edit its own MCP file. Run the +following command yourself in a normal terminal, or use LM Studio's in-app +**Edit mcp.json** action and merge the manual entry. ```bash -npx -y summer-engine@latest setup lm-studio --yes +npx -y summer-engine@latest setup lm-studio --yes --project "/absolute/path/to/project" ``` -This writes the `summer-engine` server into `~/.lmstudio/mcp.json`. Then, in LM Studio: +This updates the active LM Studio MCP config, preserves other servers, binds +Summer to the named project, and exposes the same complete Summer MCP tool +registry used by other clients. It does not require OpenCode. LM Studio has +changed config paths between releases; use **Edit mcp.json** inside LM Studio +as the source of truth rather than assuming `~/.lmstudio/mcp.json`. + +Then, in LM Studio: 1. Download a model in the **Discover** tab (see [model picks](#which-model-to-run) below). -2. Toggle the `summer-engine` MCP server on in the **Program** tab. -3. **Raise the model's context length to 32k or higher** when loading it. Models load with the context baked into their metadata — often ~4k, which MCP tool schemas overflow silently. +2. Toggle `summer-engine` under **Chat > Integrations** (**Program** in older versions). +3. Use a multi-turn tool-calling model with **64k context or more**. 4. Keep KV-cache quantization off for long agent sessions. On Apple Silicon, prefer the MLX builds. Every engine call shows a confirmation dialog you can review before it runs. +Start with `summer_get_agent_playbook`, project context, and scene tree without +mutating anything. A model that emits a tool call but cannot consume its result +is not safe for scene edits. If LM Studio reports Jinja errors such as +`Unknown ArrayValue filter: upper` or `Unknown test: sequence`, fix or replace +the model's prompt template; reducing the tool count alone does not repair it. + ## Option 2: OpenCode + Ollama (terminal) The most common pairing in 2026. Ollama serves the model; OpenCode is the agent. @@ -46,10 +73,12 @@ OLLAMA_CONTEXT_LENGTH=65536 ollama serve ollama pull qwen3-coder:30b # 3. Wire Summer Engine into OpenCode -npx -y summer-engine@latest setup opencode --yes +npx -y summer-engine@latest setup opencode --yes --project "$PWD" ``` -Then point OpenCode's provider at Ollama (`http://localhost:11434/v1` as an OpenAI-compatible endpoint) and select your model. Run `ollama ps` to confirm the bigger context hasn't pushed the model off the GPU. +This command changes only OpenCode's Summer MCP entry and guidance. Configure +the Ollama provider in OpenCode separately, then run `ollama ps` to confirm the +bigger context has not pushed the model off the GPU. The same Ollama backend works with **Kilo Code** in VS Code (`npx -y summer-engine@latest setup kilo-code --yes`) — set the context window to 32k+ in Kilo's provider settings. @@ -89,4 +118,6 @@ Tool calling is the hard part for local models. Use Q4_K_M quantization or bette | Asset library search (25k+ assets) | **Free**, rate-limited | | Cloud generation (3D, image, audio, video) | Credits | -Sign in once with `npx summer-engine login` — the account is the rate-limit key, not a paywall. +Local engine control does not require signing in. Sign in with +`npx -y summer-engine@latest login` only when you want account-backed asset +search or cloud generation; cloud generation uses credits. diff --git a/mcp/opencode.mdx b/mcp/opencode.mdx index 9445f84..5a5eaab 100644 --- a/mcp/opencode.mdx +++ b/mcp/opencode.mdx @@ -25,10 +25,34 @@ This guide covers the configuration. Setup takes about a minute. Run the Summer setup command. It writes the OpenCode config, installs the recommended skills, and runs diagnostics: ```bash -npx -y summer-engine@latest setup opencode --yes +npx -y summer-engine@latest setup opencode --yes --force --project "$PWD" ``` -This writes to your user OpenCode config (`~/.config/opencode/opencode.json` on macOS and Linux, `%APPDATA%\opencode\opencode.json` on Windows). For a single project, use `--scope project` to write `opencode.json` in the project root instead. +With `--project` and no explicit scope, this writes `opencode.json` in the +project root, binds MCP to that exact project, and installs Summer guidance. +It preserves every model and provider setting. OpenCode receives the same +complete Summer MCP tool registry as every other supported client. + + +OpenCode setup does not imply LM Studio. It works with an existing cloud +provider, Ollama, LM Studio, or any other provider already configured in +OpenCode without changing it. + + +### Optional OpenCode + LM Studio recipe + +Only when LM Studio should also become the OpenCode provider, get the exact +loaded model ID from `http://127.0.0.1:1234/v1/models` and run: + +```bash +npx -y summer-engine@latest setup opencode --yes \ + --project "$PWD" \ + --lm-studio-model "your-loaded-model-id" +``` + +Add `--lm-studio-vision` only for a model that accepts image input. This recipe +is opt-in; the plain setup command never writes `provider`, `model`, or +`small_model` keys. ### Option 2: Manual configuration @@ -42,7 +66,7 @@ Create or edit your OpenCode config and add the `summer-engine` MCP server. Open "mcp": { "summer-engine": { "type": "local", - "command": ["npx", "-y", "summer-engine@latest", "mcp"] + "command": ["npx", "-y", "summer-engine@latest", "mcp", "--project", "/absolute/path/to/project"] } } } @@ -55,7 +79,7 @@ Create or edit your OpenCode config and add the `summer-engine` MCP server. Open "other-server": { ... }, "summer-engine": { "type": "local", - "command": ["npx", "-y", "summer-engine@latest", "mcp"] + "command": ["npx", "-y", "summer-engine@latest", "mcp", "--project", "/absolute/path/to/project"] } } } @@ -75,11 +99,21 @@ Close and restart OpenCode so it loads the new config. The Summer Engine MCP ser ### Verify -List your MCP servers in OpenCode and confirm `summer-engine` appears with its tools. Then try a prompt: +Run `opencode mcp list` and confirm `summer-engine` appears. `summer doctor` +reporting registered tools is only a server boot check; it is not evidence that +OpenCode loaded those tools. Then use a +read-only prompt first: + +- "Call summer_get_agent_playbook and read its result. Then inspect the exact + project and scene tree without changing anything." -- "Use Summer Engine to add a MeshInstance3D with a BoxMesh to the scene" +Only mutate after OpenCode both calls the tools and correctly consumes their +results. -If the node appears in Summer Engine, the setup is working. +In an end-to-end smoke, the next safe step is one reversible node: add a named +`Node3D`, confirm it in `summer_get_scene_tree`, remove it, and confirm the final +tree matches the baseline. This proves client discovery, result consumption, +mutation, save, read-back, and cleanup. ## Using Summer Engine with OpenCode @@ -92,14 +126,16 @@ Once configured, OpenCode can use Summer Engine's tools when you ask for game-re - "Set the project's main scene to res://main.tscn" -**Engine must be running.** OpenCode talks to Summer Engine over localhost. Open your project in the engine first, or run `npx summer-engine run` from the project directory. +**Engine must be running.** OpenCode talks to Summer Engine over localhost. Open your project in the engine first, or run `npx -y summer-engine@latest run` from the project directory. ## Troubleshooting ### "Summer Engine is not running" -Start Summer Engine and open your project. The MCP server connects to the engine's local API on port 6550. The engine writes a token to `~/.summer/api-token` when it starts. +Start Summer Engine and open your project. Summer discovers live local editor +instances and binds to the project passed with `--project`; do not hardcode an +API port or copy an editor token into OpenCode. ### MCP server not appearing diff --git a/mcp/overview.mdx b/mcp/overview.mdx index f8ff028..ab9f717 100644 --- a/mcp/overview.mdx +++ b/mcp/overview.mdx @@ -64,7 +64,10 @@ Devin Desktop's AI can use Summer Engine's MCP tools. Configure the MCP server, ## How Do I Make Games with Antigravity? -Antigravity's AI can use Summer Engine's MCP tools. Add the config to `.vscode/mcp.json`, open your project in the engine, and build games from Antigravity: add nodes, import assets, run and debug. +Antigravity's AI can use Summer Engine's MCP tools. Run `summer setup +antigravity` to write its current `.agents/mcp_config.json` and Agent Skills, +open the same project in Summer Engine, and verify a read-only tool call before +making changes. --yes --force --project "$PWD" +``` + +Or paste this bounded instruction into a coding agent that has shell access. +Do not paste it into LM Studio Chat; use the separate manual LM Studio path +below. + +```text +Set up Summer MCP for this coding agent and the current project. The MCP client +and model provider are separate choices. Before writing anything, run +`npx -y summer-engine@latest setup --help` and confirm that the exact client +target and the `--project` option are both listed. Use `opencode` for OpenCode +and `antigravity` for Antigravity. If either requirement is missing, STOP and +report that npm latest is older than these instructions. Do not substitute a +different client, omit `--project`, change to user/global scope, or hand-edit a +fallback config. Otherwise run `npx -y summer-engine@latest setup +--yes --force --project "$PWD"`. Do not change my model provider, install the +engine, sign me in, or create a project. Show the config path. A doctor result +such as "MCP Tools registered" proves only that the server can load; it does +not prove this agent can see or call the tools. If the client needs a restart, +ask me to restart it. Before any mutation, call `summer_get_agent_playbook`, +`summer_get_project_context`, and `summer_get_scene_tree`, consume their +results, and report the exact bound project and scene. If any tool is missing +or rejected, quote the error and STOP. +``` + +| What you are using | Client target | Provider behavior | +|---|---|---| +| OpenCode with any provider | `opencode` | Provider/model config is preserved | +| LM Studio chat directly | `lm-studio` | No OpenCode required | +| Antigravity | `antigravity` | Antigravity's selected model is preserved | +| OpenCode + LM Studio | `opencode` plus explicit `--lm-studio-model ` | Optional combined recipe | + + +Do not select a client target from the model runtime alone. Ollama is a model +runtime, not an MCP client. OpenCode is still `opencode` whether it uses Ollama, +LM Studio, or a cloud provider. + + + +LM Studio Chat is an MCP host, not a shell-capable coding agent. Run +`setup lm-studio` yourself in a terminal, or use LM Studio's **Edit mcp.json** +action and the [manual local-model guide](/mcp/local-models). + ## Quick Setup by IDE @@ -46,6 +99,13 @@ The engine runs a local HTTP server on `localhost:6550` when it's open. The MCP > One-click or manual config. Most popular choice for AI-assisted development. + + Provider-neutral one-command setup, with optional local-model recipes. + +Antigravity uses its own current native config rather than the VS Code block: + +```json Antigravity (.agents/mcp_config.json) +{ + "mcpServers": { + "summer-engine": { + "command": "npx", + "args": ["-y", "summer-engine@latest", "mcp", "--project", "/absolute/path/to/project"] + } + } +} +``` + -**No global install required.** Using `npx summer-engine mcp` runs the server on demand. For faster startup, you can install globally: `npm install -g summer-engine`, then use `"args": ["summer", "mcp"]` instead. +**No global install required.** `npx -y summer-engine@latest mcp` runs the +current server on demand and avoids stale npx cache entries. ## Verify It Works -1. **Start Summer Engine**: Open your project in the engine (or run `npx summer-engine run` from the project directory). +1. **Start Summer Engine**: Open your project in the engine (or run `npx -y summer-engine@latest run` from the project directory). 2. **Restart your IDE**: So it picks up the new MCP config. -3. **Check the MCP panel**: In Cursor: Settings > MCP. You should see "summer-engine" connected, with its tools listed. -4. **Ask the AI**: "Use Summer Engine to add a MeshInstance3D with a BoxMesh to the scene root. Name it TestCube." -5. **Confirm in the engine**: The node should appear in the scene tree. +3. **Check the MCP panel**: Confirm `summer-engine` is connected and tools are listed. `doctor` alone cannot verify this client-side state. +4. **Run a read-only test**: Ask for `summer_get_agent_playbook`, then + `summer_get_project_context` and `summer_get_scene_tree` with no changes. +5. **Check the answer**: It must report the exact project and scene returned by + the tools. Tool visibility without result consumption is not enough. If you get "Summer Engine is not running," the engine isn't open or the project isn't loaded. Start the engine and try again. From 845249795172b093bfa8325161a5741e6ff3b920 Mon Sep 17 00:00:00 2001 From: Velizar Seleznev Date: Thu, 6 Aug 2026 10:14:38 +0200 Subject: [PATCH 2/2] docs: sync complete 2.8 MCP registry --- URL-POLICY.md | 19 +++--- mcp/overview.mdx | 13 +++- mcp/tools-reference.mdx | 101 +++++++++++++++++++++++++++-- package.json | 3 +- scripts/check-mcp-registry.mjs | 115 +++++++++++++++++++++++++++++++++ 5 files changed, 235 insertions(+), 16 deletions(-) create mode 100644 scripts/check-mcp-registry.mjs diff --git a/URL-POLICY.md b/URL-POLICY.md index 8863ad3..409d412 100644 --- a/URL-POLICY.md +++ b/URL-POLICY.md @@ -100,20 +100,23 @@ Some namespace names do not match their sidebar label — `/auto-mode/*` is labe "Using Summer". **Leave them.** The label is free to change; the path is not. This mismatch is a small permanent ugliness and it is the correct trade. -## Generated pages +## Generated-page targets -Some pages are generated from source and must not be hand-edited. They carry a -banner saying so. Editing them by hand produces a change that is silently reverted on -the next generation, and worse, a page that disagrees with what actually ships. +Some reference pages are intended to be generated from product source. A page +is actually generated only when its frontmatter contains `generated: true` and +names its `generator`; those pages must not be hand-edited. The checker enforces +that contract. Pages without that marker remain checked-in documentation and +must be updated from the owning source plus their repository checks until their +generator exists. Generated pages publish to their existing frozen URLs rather than to a new `/reference/*` namespace, for the reason this whole document exists: -| Page | Generated from | +| Page | Current source contract | |---|---| -| `/ai-tools/operations` | The engine's unified operation registry | -| `/mcp/tools-reference` | The MCP server's tool definitions | -| `/mcp/cli-reference` | The CLI's command definitions | +| `/ai-tools/operations` | Keep aligned with the engine's unified operation registry until a generator is attached. | +| `/mcp/tools-reference` | Keep aligned with the canonical MCP server definitions; `npm run check:mcp-registry` verifies the complete 2.8 inventory. | +| `/mcp/cli-reference` | Keep aligned with the CLI command definitions until a generator is attached. | If a generated page is wrong, fix the source. Never the page. diff --git a/mcp/overview.mdx b/mcp/overview.mdx index ab9f717..68fb7ad 100644 --- a/mcp/overview.mdx +++ b/mcp/overview.mdx @@ -1,10 +1,10 @@ --- title: "MCP: Build Games with AI" -description: "How to make games with AI: Cursor, Claude Code, Devin Desktop, Antigravity, Codex, Gemini, GitHub Copilot, OpenCode, VS Code, Zed. Summer Engine MCP, CLI, and API. 50+ tools." +description: "How to make games with AI: Cursor, Claude Code, Devin Desktop, Antigravity, Codex, Gemini, GitHub Copilot, OpenCode, VS Code, Zed. Summer Engine MCP, CLI, and API." icon: "plug" --- -{/* Do not reintroduce a hardcoded MCP tool count here. The tool list grows every release and a baked-in number has already gone stale twice. */} +{/* Do not add an unversioned "current" MCP count here. The release comparison below is deliberately versioned and checked against the 2.8 registry contract. */} ## How Do I Make Games with AI? @@ -160,6 +160,13 @@ The CLI lets you install Summer Engine, create projects, run the engine, and con Summer Engine's MCP server exposes its tools over the Model Context Protocol. The same operations the built-in chat uses (AddNode, SetProp, SaveScene, ImportFromUrl) are available to any MCP-compatible AI tool, plus asset library search, AI generation of images, 3D models, audio, video, and motion, and [Summer Cloud](/guides/summer-cloud) project sync. See the [API Reference](/api-reference/mcp) and [Tools Reference](/mcp/tools-reference). +The `summer-engine` 2.8 candidate exposes 62 MCP tools through `tools/list`. That +is the complete package registry, not the smaller local-operation registry in +a particular desktop engine build. The published 2.7.0 package exposes 58; +2.8 adds exactly `summer_creator_publish`, `summer_creator_releases`, +`summer_creator_logs`, and `summer_creator_config`. The client onboarding, +project binding, and editor-routing changes do not add any other tools. + diff --git a/package.json b/package.json index 45f6d45..4188623 100644 --- a/package.json +++ b/package.json @@ -6,12 +6,13 @@ "node": ">=20" }, "scripts": { - "check": "npm run check:compatibility && npm run check:language && npm run check:capabilities && npm run check:policy-fixtures && npm run check:routes && node scripts/check-docs.mjs", + "check": "npm run check:compatibility && npm run check:language && npm run check:capabilities && npm run check:mcp-registry && npm run check:policy-fixtures && npm run check:routes && node scripts/check-docs.mjs", "check:capabilities": "node scripts/check-capabilities.mjs", "check:policy-fixtures": "node scripts/check-policy-fixtures.mjs", "check:compatibility": "node scripts/sync-engine-compatibility.mjs --check", "check:external-links": "node scripts/check-external-links.mjs", "check:language": "node scripts/check-language.mjs", + "check:mcp-registry": "node scripts/check-mcp-registry.mjs", "check:routes": "node scripts/check-routes.mjs", "generate:compatibility": "node scripts/sync-engine-compatibility.mjs", "generate:routes": "node scripts/check-routes.mjs --write" diff --git a/scripts/check-mcp-registry.mjs b/scripts/check-mcp-registry.mjs new file mode 100644 index 0000000..17636f9 --- /dev/null +++ b/scripts/check-mcp-registry.mjs @@ -0,0 +1,115 @@ +import { readFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +const reference = readFileSync(resolve(root, "mcp/tools-reference.mdx"), "utf8"); +const overview = readFileSync(resolve(root, "mcp/overview.mdx"), "utf8"); +const expectedTools = [ + "summer_add_node", + "summer_batch", + "summer_check_job", + "summer_clear_console", + "summer_cloud_checkpoints", + "summer_cloud_conflicts", + "summer_cloud_init", + "summer_cloud_pull", + "summer_cloud_push", + "summer_cloud_restore", + "summer_cloud_status", + "summer_connect_signal", + "summer_create_debug_report", + "summer_create_scene", + "summer_creator_config", + "summer_creator_logs", + "summer_creator_publish", + "summer_creator_releases", + "summer_generate_3d", + "summer_generate_audio", + "summer_generate_image", + "summer_generate_motion", + "summer_generate_video", + "summer_get_agent_playbook", + "summer_get_asset", + "summer_get_asset_download_url", + "summer_get_console", + "summer_get_debugger_errors", + "summer_get_debugger_warnings", + "summer_get_diagnostics", + "summer_get_project_context", + "summer_get_scene_tree", + "summer_get_script_errors", + "summer_get_studio_workflow", + "summer_import_asset", + "summer_import_asset_by_id", + "summer_import_from_url", + "summer_import_from_url_batch", + "summer_input_map_bind", + "summer_inspect_node", + "summer_inspect_resource", + "summer_instantiate_scene", + "summer_is_running", + "summer_list_my_assets", + "summer_open_main_scene", + "summer_open_scene", + "summer_play", + "summer_project_setting", + "summer_read_file", + "summer_remove_node", + "summer_replace_node", + "summer_replace_text", + "summer_save_scene", + "summer_screenshot", + "summer_search_assets", + "summer_select_node", + "summer_set_prop", + "summer_set_resource_property", + "summer_slice_asset_sheet", + "summer_start_game_task", + "summer_stop", + "summer_write_file", +]; +const headings = [...reference.matchAll(/^### (summer_[a-z0-9_]+)\s*$/gm)].map( + (match) => match[1], +); +const unique = new Set(headings); +const creatorAdditions = [ + "summer_creator_publish", + "summer_creator_releases", + "summer_creator_logs", + "summer_creator_config", +]; + +if (headings.length !== 62 || unique.size !== 62) { + throw new Error( + `MCP tools reference must contain 62 unique tool headings; found ${headings.length} headings and ${unique.size} unique names.`, + ); +} + +const actualTools = [...unique].sort(); +if (JSON.stringify(actualTools) !== JSON.stringify(expectedTools)) { + const missing = expectedTools.filter((tool) => !unique.has(tool)); + const extra = actualTools.filter((tool) => !expectedTools.includes(tool)); + throw new Error( + `MCP tools reference differs from the canonical 2.8 inventory. Missing: ${missing.join(", ") || "none"}. Extra: ${extra.join(", ") || "none"}.`, + ); +} + +for (const tool of [ + "summer_get_studio_workflow", + "summer_slice_asset_sheet", + ...creatorAdditions, +]) { + if (!unique.has(tool)) throw new Error(`MCP tools reference is missing ${tool}.`); +} + +for (const text of [reference, overview]) { + if (!text.includes("2.7.0") || !text.includes("58") || !text.includes("2.8")) { + throw new Error("MCP docs must retain the versioned 2.7.0 (58) to 2.8 (62) registry comparison."); + } + for (const tool of creatorAdditions) { + if (!text.includes(tool)) throw new Error(`MCP release comparison is missing ${tool}.`); + } +} + +console.log("mcp registry docs: PASS (62 unique tools; 2.7.0 58 -> 2.8.0 62)");