SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Agent chat: serve the bundled skills' reference through an MCP tool (#4966) (#4970)
raykholo36a354e3a757
diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rsindex 7f2d091dfc..758884f30d 100644--- a/crates/mcp/src/lib.rs+++ b/crates/mcp/src/lib.rs@@ -11,6 +11,7 @@mod backend;mod server;+mod skill_reference;mod tools;pub use backend::{Backend, Headless, Remote};diff --git a/crates/mcp/src/skill_reference.rs b/crates/mcp/src/skill_reference.rsnew file mode 100644index 0000000000..251163acc7--- /dev/null+++ b/crates/mcp/src/skill_reference.rs@@ -0,0 +1,50 @@+//! Read-only access to the skill documents shipped with SolidCraft.++use serde_json::{Map, Value};++struct Skill {+ name: &'static str,+ files: &'static [(&'static str, &'static str)],+}++// Exact names only: these are embedded documents, never filesystem paths to open.+const SKILLS: &[Skill] = &[+ Skill {+ name: "solidcraft-checking",+ files: &[+ ("SKILL.md", include_str!("../../../skills/solidcraft-checking/SKILL.md")),+ ("reference/porting.md", include_str!("../../../skills/solidcraft-checking/reference/porting.md")),+ ],+ },+ Skill { name: "solidcraft-editing", files: &[("SKILL.md", include_str!("../../../skills/solidcraft-editing/SKILL.md"))] },+ Skill {+ name: "solidcraft-mechanisms",+ files: &[+ ("SKILL.md", include_str!("../../../skills/solidcraft-mechanisms/SKILL.md")),+ ("reference.md", include_str!("../../../skills/solidcraft-mechanisms/reference.md")),+ ],+ },+ Skill {+ name: "solidcraft-modeling",+ files: &[+ ("SKILL.md", include_str!("../../../skills/solidcraft-modeling/SKILL.md")),+ ("reference.md", include_str!("../../../skills/solidcraft-modeling/reference.md")),+ ],+ },+];++pub(crate) fn read(args: &Map<String, Value>) -> Result<Value, String> {+ let name = args.get("skill").and_then(Value::as_str).ok_or("`skill` is required and must be a string")?;+ let skill = SKILLS+ .iter()+ .find(|s| s.name == name)+ .ok_or_else(|| format!("Unknown skill. Available skills: {}", SKILLS.iter().map(|s| s.name).collect::<Vec<_>>().join(", ")))?;+ let file = match args.get("file") {+ None | Some(Value::Null) => "reference.md",+ Some(Value::String(file)) => file,+ Some(_) => return Err("`file` must be a string".into()),+ };+ skill.files.iter().find(|(name, _)| *name == file).map(|(_, text)| Value::String((*text).into())).ok_or_else(|| {+ format!("Unknown file for {}. Available files: {}", skill.name, skill.files.iter().map(|(name, _)| *name).collect::<Vec<_>>().join(", "))+ })+}diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rsindex fdd13a8318..9fb35f362b 100644--- a/crates/mcp/src/tests.rs+++ b/crates/mcp/src/tests.rs@@ -140,6 +140,7 @@ fn handshake_and_tools_list() {"undo","redo","crash_reports",+ "skill_reference","running","new_design","open",@@ -166,6 +167,67 @@ fn handshake_and_tools_list() {assert_eq!(call(&mut s, 8, "nope/nope", json!({}))["error"]["code"], -32601);}+#[test]+fn skill_reference_returns_bundled_text_without_backend_calls() {+ let mut b = Recorder { calls: Vec::new(), batch: Err("unused".into()) };+ let docs = [+ ("solidcraft-modeling", "reference.md", include_str!("../../../skills/solidcraft-modeling/reference.md")),+ ("solidcraft-mechanisms", "reference.md", include_str!("../../../skills/solidcraft-mechanisms/reference.md")),+ ("solidcraft-checking", "reference/porting.md", include_str!("../../../skills/solidcraft-checking/reference/porting.md")),+ ("solidcraft-modeling", "SKILL.md", include_str!("../../../skills/solidcraft-modeling/SKILL.md")),+ ("solidcraft-mechanisms", "SKILL.md", include_str!("../../../skills/solidcraft-mechanisms/SKILL.md")),+ ("solidcraft-checking", "SKILL.md", include_str!("../../../skills/solidcraft-checking/SKILL.md")),+ ("solidcraft-editing", "SKILL.md", include_str!("../../../skills/solidcraft-editing/SKILL.md")),+ ];+ for (skill, file, expected) in docs {+ let args = json!({"skill": skill, "file": file});+ let r = crate::call_tool(&mut b, "skill_reference", &args);+ assert_ne!(r["isError"], true, "{r}");+ assert_eq!(r["content"][0]["text"], expected);+ if file == "reference.md" {+ assert_eq!(crate::call_tool(&mut b, "skill_reference", &json!({"skill": skill})), r);+ }+ }+ assert!(b.calls.is_empty(), "{:?}", b.calls);+}++#[test]+fn skill_reference_refuses_unknown_names_and_paths_with_available_choices() {+ let mut s = server();+ let skills = ["solidcraft-checking", "solidcraft-editing", "solidcraft-mechanisms", "solidcraft-modeling"];+ for skill in ["unknown", "../solidcraft-modeling", "/tmp/solidcraft-modeling"] {+ let r = raw_tool(&mut s, "skill_reference", json!({"skill": skill}));+ assert_eq!(r["result"]["isError"], true, "{r}");+ let text = r["result"]["content"][0]["text"].as_str().unwrap();+ for available in skills {+ assert!(text.contains(available), "{text}");+ }+ }+ for file in ["missing.md", "../reference.md", "/etc/passwd", "reference/../reference.md"] {+ let r = raw_tool(&mut s, "skill_reference", json!({"skill": "solidcraft-modeling", "file": file}));+ assert_eq!(r["result"]["isError"], true, "{r}");+ let text = r["result"]["content"][0]["text"].as_str().unwrap();+ assert!(text.contains("Available files: SKILL.md, reference.md"), "{text}");+ }+ for (skill, files) in [("solidcraft-checking", "SKILL.md, reference/porting.md"), ("solidcraft-editing", "SKILL.md")] {+ let r = raw_tool(&mut s, "skill_reference", json!({"skill": skill}));+ assert_eq!(r["result"]["isError"], true, "{r}");+ assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains(files), "{r}");+ }+}++#[test]+fn skill_reference_is_advertised_as_read_only() {+ let mut s = server();+ let r = call(&mut s, 1, "tools/list", json!({}));+ let t = r["result"]["tools"].as_array().unwrap().iter().find(|t| t["name"] == "skill_reference").expect("skill_reference tool");+ assert_eq!(t["annotations"]["readOnlyHint"], true);+ assert_eq!(t["annotations"]["destructiveHint"], false);+ assert_eq!(t["annotations"]["openWorldHint"], false);+ assert_eq!(t["inputSchema"]["required"], json!(["skill"]));+ assert_eq!(t["inputSchema"]["properties"]["file"]["default"], "reference.md");+}+/// A URDF goes through `export` with its own options (#719).#[test]fn export_tool_writes_a_urdf_package() {@@ -1609,7 +1671,7 @@ fn tool_annotations_tell_the_whole_truth() {for name in ["execute", "batch", "save", "export", "open", "screenshot"] {assert_eq!(hints(name), (false, true, true), "{name}");}- for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports", "running"] {+ for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports", "skill_reference", "running"] {assert_eq!(hints(name), (true, false, false), "{name}");}assert_eq!(hints("new_design"), (false, true, false));diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rsindex 5453c8031e..e464adf536 100644--- a/crates/mcp/src/tools.rs+++ b/crates/mcp/src/tools.rs@@ -304,6 +304,21 @@ pub fn tool_definitions() -> Vec<Value> {),Effect::Files,),+ tool(+ "skill_reference",+ "Skill reference",+ "Read a document of SolidCraft's bundled agent skills (solidcraft-modeling, solidcraft-mechanisms, \+ solidcraft-editing, solidcraft-checking) from the copy built into SolidCraft. `file` defaults to reference.md; \+ each skill also has SKILL.md. Unknown skills or files are refused with the available ones.",+ obj(+ json!({+ "skill": string("Skill name, such as solidcraft-modeling"),+ "file": {"type": "string", "description": "Document of that skill", "default": "reference.md"},+ }),+ &["skill"],+ ),+ Effect::ReadOnly,+ ),]}@@ -464,6 +479,7 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<VSome(_) => exec(b, "diagnostics.crash_report", pick(a, &["id"])),None => exec(b, "diagnostics.crash_reports", pick(a, &["limit"])),},+ "skill_reference" => crate::skill_reference::read(a),"running" => b.call("control.running", json!({})),"undo" => exec(b, "edit.undo", json!({})),"redo" => exec(b, "edit.redo", json!({})),diff --git a/docs/mcp.md b/docs/mcp.mdindex 5741e16954..c4790c03af 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -109,8 +109,8 @@ file dialogs are never limited.### Tool annotationsEach tool says what it may do, for clients that ask before running tools (or auto-approve on-these hints). `list_commands`, `describe_command`, `inspect_design`, `measure`, `body_topology`-and `crash_reports` are read-only. `set_parameter`, `undo` and `redo` change the design undoably.+these hints). `list_commands`, `describe_command`, `inspect_design`, `measure`, `body_topology`,+`skill_reference` and `crash_reports` are read-only. `set_parameter`, `undo` and `redo` change the design undoably.`new_design` replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and`screenshot` (whose `path` writes a file) can read, write, overwrite or delete files: they arenot read-only, `destructiveHint` and `openWorldHint` are true.@@ -148,6 +148,8 @@ Claude Desktop (`claude_desktop_config.json`), bridged to a running app:They cover the workflow, the command shapes, how to verify with `measure`, and the known traps. With them an agent builds a part in a few `batch` calls and reads far less output. To install them for Claude Code, copy the folders into `~/.claude/skills/`; [skills/README.md](https://github.com/bherbruck/solidcraft/blob/main/skills/README.md) has the details.+The `skill_reference` tool returns these documents from the copies built into SolidCraft, so an agent without file access can follow them: `{"skill": "solidcraft-modeling"}` returns its `reference.md`, the default file. Mechanisms also has `reference.md`, checking has `reference/porting.md`, and every skill has `SKILL.md` (editing uses modeling's reference). It never reads a path from disk, and an unknown skill or file is refused with the available choices. SolidCraft's own chat turns the agent's file tools off, so this is how its agent reads the skills there.+## Tools| Tool | Arguments | What it does |@@ -164,6 +166,7 @@ They cover the workflow, the command shapes, how to verify with `measure`, and t| `export` | `path`, `format?` (step, 3mf, 3mf-tagged, stl, stla, obj, urdf), `bodies?`, `mesh_prefix?`, `effort?`, `velocity?` | STEP, 3MF or mesh export; URDF writes the whole assembly with its meshes next to it (`docs/urdf.md`). || `undo`, `redo` | — | Undo / redo one change. || `crash_reports` | `id?`, `limit?` | The crash reports on this computer, newest first; with `id`, the whole report (backtrace, command, recent commands, `design_path`/`replay_path`). See [crash-reports.md](crash-reports.md). |+| `skill_reference` | `skill`, `file?` (default `reference.md`) | Read a bundled skill document. Skills: `solidcraft-modeling`, `solidcraft-mechanisms`, `solidcraft-editing`, `solidcraft-checking`. || `running` | - | What the app is running or has queued, for every client (`control.running`, see [control-protocol.md](control-protocol.md#limits)): each request's connection and id, method, command id or a batch's step count, `running_s` and `queued`, never its parameters. Answers at once while the app is busy: ask it when a call timed out before sending a change again. Headless: always `{"running": []}`. || `new_design` | `name?` | Start an empty design. || `open` | `path` | Open a `.solidcraft` design, a STEP file (`.step`/`.stp`) as a new design holding its bodies (an Import base feature), or a 3MF/STL file as mesh bodies. |diff --git a/skills/README.md b/skills/README.mdindex a2b1b868b3..ac37f254f0 100644--- a/skills/README.md+++ b/skills/README.md@@ -4,6 +4,9 @@ Skills for AI agents that model in SolidCraft through its [MCP server](../docs/mone skill in the [Agent Skills](https://agentskills.io) format: a `SKILL.md` with a name and adescription that tell the agent when to load it, and an optional supporting reference file.+The same documents are built into SolidCraft: its MCP server's `skill_reference` tool returns them, so an+agent without file access (such as the one in SolidCraft's own chat) can still read a skill's reference.+| Skill | Loads when the agent ||---|---|| [`solidcraft-modeling`](solidcraft-modeling/SKILL.md) | builds a new part (enclosure, bracket, plate, flange, …) |diff --git a/skills/solidcraft-checking/SKILL.md b/skills/solidcraft-checking/SKILL.mdindex 304e8bd8e8..900a3536fd 100644--- a/skills/solidcraft-checking/SKILL.md+++ b/skills/solidcraft-checking/SKILL.md@@ -25,7 +25,7 @@ In `$SKILL/scripts/`:1. **Parameters and features.** Each parameter comment states the allowed range ("whole number, 4 or more"): the user reads it in the Parameters table, and SolidCraft enforces no range. Derive sizes from measured values, so that a count parameter changes how many features there are, not how big they are. An expression that more than one sketch or feature uses becomes a named parameter. Add the derived numbers the user needs (parts to print) and mark the driving parameters favourite (`parameters.favorite`). Give each thing the user thinks of (a port, a row of standoffs) its own feature, named after it, so it can be found and changed on its own. Choose the origin so that no sketch dimension reaches 0 for any allowed value (trap 1).2. **Every sketch at dof 0.** A sketch with dof left can solve to a different shape after a parameter change, without an error. `run.py` lists them.3. **Every allowed value.** One script of `parameters.change` commands walks each driving parameter to both ends of its range, one change after another, and back to the default, as edits in the app do: trap 1 fails only on the change after the one that reaches 0. Put a `document.inspect {measure: true}` after each end of a range and run the walk with `run.py walk.json --in <design>`. Every state must be clean: no `FAIL`, no `SKETCH`, and `BODY` volumes and centres of mass that match the values you compute for that state. A boolean retry can leave the geometry wrong with only a `WARN` line, and the volume shows it (trap 4); a mirrored sketch (trap 1) keeps the volume and moves the centre of mass.-4. **Exact check** when a port has a reference, or a volume gap leaves doubt: export STEP (`file.export {path, bodies}`) and run `compare_step.py`. Before porting, read `$SKILL/reference/porting.md`.+4. **Exact check** when a port has a reference, or a volume gap leaves doubt: export STEP (`file.export {path, bodies}`) and run `compare_step.py`. Before porting, in SolidCraft's own chat or any MCP client, call `skill_reference {"skill":"solidcraft-checking","file":"reference/porting.md"}`. Elsewhere, read `$SKILL/reference/porting.md`.5. **Kept in a repo.** Save as `<name>.json` with `run.py build.json --save <name>.json`: a `.json` design stays plain JSON when it is saved again, so git diffs stay readable. Saving over a file leaves `<name>.json.bak`, so ignore `*.bak`. From then on the design file is the source, and changes go into it with `--in <design> --save <design>`. Copy `$SKILL/templates/test_design.py` next to the design, fill in its cases, set its tolerance as its comment says, and run it until it passes. Expected values come from an exact reference when porting, from hand calculation for simple shapes, or from a build the user has reviewed. After a change, update frozen values only where the change is meant to change them.## Trapsdiff --git a/skills/solidcraft-editing/SKILL.md b/skills/solidcraft-editing/SKILL.mdindex abc881d3d5..f592ec70e3 100644--- a/skills/solidcraft-editing/SKILL.md+++ b/skills/solidcraft-editing/SKILL.md@@ -6,7 +6,7 @@ description: Use when changing, fixing or extending an existing SolidCraft desig# SolidCraft editing## Overview-Edit an existing design through its parameters instead of rebuilding it. Every sketch dimension and feature input is already a parameter (`d1`, `d2`, ...), so most edits are a `parameters.change` each, sent together in one batch. Map the design with a few compact calls rather than walking the timeline one feature at a time. For command shapes and traps, use `reference.md` from the `solidcraft-modeling` skill.+Edit an existing design through its parameters instead of rebuilding it. Every sketch dimension and feature input is already a parameter (`d1`, `d2`, ...), so most edits are a `parameters.change` each, sent together in one batch. Map the design with a few compact calls rather than walking the timeline one feature at a time. For command shapes and traps, in SolidCraft's own chat or any MCP client, call `skill_reference {"skill":"solidcraft-modeling"}`. Elsewhere, use `reference.md` from the `solidcraft-modeling` skill.## Map the design (3-4 calls)1. **Open:** if the design is not open yet, run `open {path}`. When the server is bridged to the app and the current design is `dirty`, ask before opening anything.diff --git a/skills/solidcraft-mechanisms/SKILL.md b/skills/solidcraft-mechanisms/SKILL.mdindex 7f6d7639a5..0d40280195 100644--- a/skills/solidcraft-mechanisms/SKILL.md+++ b/skills/solidcraft-mechanisms/SKILL.md@@ -11,7 +11,7 @@ An assembly is components placed by joints. Work the mechanism out as world poinWritten against SolidCraft `main` after 0.11.1, which counts the degrees of freedom of closed loops, carries motion links through chains made in any order, and answers drives in degrees with `moved` (and a `reason` when nothing could move).## Before the first call-1. Read `reference.md`.+1. In SolidCraft's own chat or any MCP client, call `skill_reference {"skill":"solidcraft-mechanisms"}`. Elsewhere, read `reference.md`.2. **Open:** if the design is not open yet, run `open {path}`. When the server is bridged to the app and the current design is `dirty`, ask before opening anything.3. **Map it:** run `inspect_design {"measure":false,"sketches":false}`, then `execute joint.list`. `joint.list` shows `fixed` (the grounded occurrences, always with the root, 0), `dof` per occurrence, `conflicts`, the joints, links and named origins, at about 0.5 KB per joint. `execute motion.list` lists the motion studies.4. **Existing design:** take `edit.checkpoint` in its own call before you move bodies into components. `edit.restore_checkpoint {checkpoint}` goes back exactly.diff --git a/skills/solidcraft-modeling/SKILL.md b/skills/solidcraft-modeling/SKILL.mdindex be74e91be9..aa15f9afcf 100644--- a/skills/solidcraft-modeling/SKILL.md+++ b/skills/solidcraft-modeling/SKILL.md@@ -9,7 +9,7 @@ description: Use when building a new part, enclosure, bracket, plate, flange orWork the part out as numbers first. Then build it in a few large `batch` calls, and check each stage with `measure` against values you computed yourself. A clean build takes 3-4 build batches, about 10-13 calls with the checks. Command shapes, plane axes, ids, reply sizes and known traps are in `reference.md` next to this file, so you do not need to explore the command catalog.## Before the first call-1. Read `reference.md`.+1. In SolidCraft's own chat or any MCP client, call `skill_reference {"skill":"solidcraft-modeling"}`. Elsewhere, read `reference.md`.2. Run `inspect_design {"measure":false,"sketches":false}`, even when you think the session is empty.- The SolidCraft server's instructions end with `Backend: connected to the SolidCraft app` when it drives the user's open app, and with `Backend: headless` otherwise.- If the design has timeline features, ask before calling `new_design` or `open`, because both discard unsaved work. You can also build into the open design.