MCP: docs/mcp.md, README section, attribution

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01AS5Tn3xieewUSg3uxrMVdL

ATTRIBUTION.md

@@ -28,4 +28,6 @@ Generated-in-code assets are original and have no file to list:
 | crates/ui-egui/src/lib.rs (screenshot queue, synthetic input) | CADCraft `crates/ui-egui/src/lib.rs` | MIT OR Apache-2.0 |
 | crates/ui-egui/src/control.rs (method dispatch and screenshot saving) | CADCraft `crates/ui-egui/src/control.rs` | MIT OR Apache-2.0 |
 | crates/ui-egui/src/gpu.rs (paint-callback structure) | CADCraft `crates/ui-egui/src/gpu.rs` | MIT OR Apache-2.0 |
+| crates/mcp/src/server.rs, crates/mcp/src/backend.rs (JSON-RPC framing, MCP lifecycle, control-port bridge) | CADCraft `crates/mcp/src/{server,backend}.rs` | MIT OR Apache-2.0 |
+| crates/mcp/src/tools.rs (tool schema helpers and argument checking) | CADCraft `crates/mcp/src/tools.rs`, GridCraft `crates/mcp/src/tools.rs` | MIT OR Apache-2.0 |
 | LICENSE-MIT, LICENSE-APACHE (licence text) | CADCraft | — |

NOTICE

@@ -10,7 +10,7 @@ Software dependencies are listed in Cargo.lock. The geometry kernel builds on th
 dependencies, https://github.com/ricosjp/truck), licensed under the Apache License 2.0 and used
 unmodified as libraries.
 
-Some code is adapted from sibling projects in the storytold family (CADCraft), which are
+Some code is adapted from sibling projects in the storytold family (CADCraft, GridCraft), which are
 licensed MIT OR Apache-2.0; ATTRIBUTION.md lists the files.
 
 None of the bundled assets come from third parties: every icon is drawn in code. The per-file

README.md

@@ -35,6 +35,8 @@ storytold "craft" family.
   control channel so agents and tests can drive it.
 - **Headless CLI** `solvecraft-cli`: run command scripts, measure (volume, area, centre of mass,
   face/edge/vertex counts), export, render PNG snapshots, replay Fusion oracle recipes.
+- **MCP server** `solvecraft-cli mcp`: AI agents model, measure and look at parts headless or
+  in the running app (see below).
 
 ## Build and run
 
@@ -61,6 +63,16 @@ A script is a JSON list of commands, the same ones the UI runs:
 ]}
 ```
 
+## AI agents (MCP)
+
+`solvecraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on
+stdio. Headless it runs its own design session; with `--connect 127.0.0.1:PORT` it drives the app
+started with `solvecraft --control PORT`, so you can watch the agent model. Tools:
+`list_commands`, `execute`, `batch`, `inspect_design`, `measure`, `body_topology`,
+`set_parameter`, `screenshot` (returns the image), `export`, `undo`, `redo`, `new_design`, `open`,
+`save`. Claude Code: `claude mcp add solvecraft -- solvecraft-cli mcp`. Details, client
+configuration and an example session: [docs/mcp.md](docs/mcp.md).
+
 ## Architecture
 
 | Layer | Crates | Role |
@@ -70,7 +82,7 @@ A script is a JSON list of commands, the same ones the UI runs:
 | L2 | `doc` | parameters, expressions, the feature timeline and its incremental evaluation |
 | L3 | `io` | design files, STL/OBJ/STEP export |
 | L4 | `engine` | the session and the command registry (everything is a command) |
-| L5 | `ui-egui` | the swappable desktop front end |
+| L5 | `ui-egui`, `mcp` | the swappable desktop front end; the MCP server (headless or bridged to the app) |
 | apps | `solvecraft`, `solvecraft-cli` | desktop app, headless CLI |
 
 ## Licence

docs/control-protocol.md

@@ -35,6 +35,11 @@ Commands never open dialogs when run this way. `solvecraft-cli commands` prints
 | `ui.resize` | `width`, `height` | |
 | `app.quit` | — | |
 
+## MCP
+
+`solvecraft-cli mcp --connect 127.0.0.1:PORT` bridges an MCP client (an AI agent) to this
+channel; see [mcp.md](mcp.md).
+
 ## Example
 
 ```text

docs/mcp.md

@@ -0,0 +1,98 @@
+# SolveCraft and AI agents (MCP)
+
+SolveCraft speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio
+(JSON-RPC 2.0, one message per line; protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05).
+An agent models exactly like a person does: every tool runs engine commands, the same ones the
+toolbar, palette, scripts and control channel use, and never opens a dialog.
+
+## Start it
+
+```sh
+# Headless: an in-process design session, no window (CPU renders for screenshots).
+solvecraft-cli mcp
+
+# Headless, starting from a design file or a command script.
+solvecraft-cli mcp --in part.solvecraft
+
+# Bridged to the running app, so you can watch the agent model:
+solvecraft --control 7878 &
+solvecraft-cli mcp --connect 127.0.0.1:7878
+```
+
+stdout carries only protocol messages; errors go to stderr. Bridged screenshots are written to a
+temporary file by the app and read back by the server, so both must run on the same machine.
+
+### Client configuration
+
+Claude Code (project `.mcp.json`, or `claude mcp add solvecraft -- solvecraft-cli mcp`):
+
+```json
+{
+  "mcpServers": {
+    "solvecraft": { "command": "solvecraft-cli", "args": ["mcp"] }
+  }
+}
+```
+
+Claude Desktop (`claude_desktop_config.json`), bridged to a running app:
+
+```json
+{
+  "mcpServers": {
+    "solvecraft": { "command": "/path/to/solvecraft-cli", "args": ["mcp", "--connect", "127.0.0.1:7878"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | Arguments | What it does |
+|---|---|---|
+| `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. |
+| `execute` | `command`, `params?` | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. |
+| `batch` | `commands: [{command, params}]`, `rollback?` (default true) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`) and every result before it. |
+| `inspect_design` | `measure?` (default true), `sketches?` (default true) | Parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts), sketches (curves, points, constraints, profiles, DOF, solve status), selection, undo depth. |
+| `measure` | `body?` | Volume (mm³), area (mm²), centre of mass, bbox and topology counts per body, with totals. |
+| `body_topology` | `body` | Edges (index, midpoint, length, ends) and faces (index, area, centroid, normal). An edge midpoint is the `[x,y,z]` that picks that edge for fillet and chamfer. |
+| `set_parameter` | `name`, `value` (number or expression), `unit?`, `comment?` | Create or change a user parameter and recompute; reports features that now fail. |
+| `screenshot` | `view?` (iso, top, front, back, bottom, left, right, home, fit), `path?`, `width?`, `height?`, `source?` (window, model) | A PNG image content block. Headless: CPU render fitted to the model. Bridged: the app window (default) or a model render with the app's camera. |
+| `export` | `path`, `format?` (step, stl, stla, obj), `bodies?` | STEP or mesh export. |
+| `undo`, `redo` | — | Undo / redo one change. |
+| `new_design` | `name?` | Start an empty design. |
+| `open` | `path` | Open a `.solvecraft` design. |
+| `save` | `path?` | Save the design (to its current file without `path`). |
+
+Resources: `solvecraft://design` (inspect JSON with measurements) and `solvecraft://commands`
+(the catalog).
+
+Errors: an unknown tool or arguments that don't match the tool's schema are JSON-RPC
+`-32602` errors; an engine failure (bad command parameters, a feature that fails) is a tool
+result with `isError: true` and the engine's message, which the model can read and correct.
+
+`batch` rollback undoes as many steps as the batch added to the undo history; batches that
+themselves call `UndoCommand`, `NewDocumentCommand` or `doc.open` are not rolled back exactly.
+
+## A typical session
+
+```text
+→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"1"}}}
+→ {"jsonrpc":"2.0","method":"notifications/initialized"}
+→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"batch","arguments":{"commands":[
+     {"command":"SketchCreate","params":{"plane":"XY"}},
+     {"command":"ShapeRectangleTwoPoint","params":{"p0":[0,0],"p1":[40,30]}},
+     {"command":"SketchStop"},
+     {"command":"Extrude","params":{"distance":20}},
+     {"command":"FusionFilletEdgesCommand","params":{"edges":[[0,0,10]],"radius":3}},
+     {"command":"SketchCreate","params":{"plane":"XY"}},
+     {"command":"CircleCenterRadius","params":{"center":[20,15],"radius":5}},
+     {"command":"Extrude","params":{"distance":20,"operation":"cut"}}]}}}
+← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"ok\": true, \"completed\": 8, \"results\": [...]}"}]}}
+→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"measure","arguments":{}}}
+← … "total": {"volume_mm3": 22390.6, …}
+→ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"screenshot","arguments":{"view":"iso"}}}
+← {"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"image","mimeType":"image/png","data":"iVBORw0…"},{"type":"text","text":"{\"source\":\"model\",…}"}]}}
+→ {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"export","arguments":{"path":"/tmp/part.step"}}}
+```
+
+The tests in `crates/mcp/src/tests.rs` run sessions like this (box → fillet → hole, parameters,
+batch rollback, hostile arguments) and check the results only through MCP.