SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
MCP: docs/mcp.md, README section, attribution
bherbruck3e9042b6de53
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.mdindex 209f6e9b9f..1b05096092 100644--- a/ATTRIBUTION.md+++ b/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 | — |diff --git a/NOTICE b/NOTICEindex 3ab2b2bf2d..27f1cf20f0 100644--- a/NOTICE+++ b/NOTICE@@ -10,7 +10,7 @@ Software dependencies are listed in Cargo.lock. The geometry kernel builds on thdependencies, https://github.com/ricosjp/truck), licensed under the Apache License 2.0 and usedunmodified 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 arelicensed 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-filediff --git a/README.md b/README.mdindex c4c4710df5..ed2249988f 100644--- a/README.md+++ b/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 |## Licencediff --git a/docs/control-protocol.md b/docs/control-protocol.mdindex 43c44cc89e..78c7e0264a 100644--- a/docs/control-protocol.md+++ b/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```textdiff --git a/docs/mcp.md b/docs/mcp.mdnew file mode 100644index 0000000000..0a6cbabaf5--- /dev/null+++ b/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.