Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

MCP: server and tools

bherbruckd1ff23990e95
diff --git a/Cargo.lock b/Cargo.lock
index cec49f72fd..ac5a619b7b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3070,6 +3070,7 @@ version = "0.1.0"
dependencies = [
"serde_json",
"solvecraft-engine",
+ "solvecraft-mcp",
]
[[package]]
@@ -3134,6 +3135,14 @@ dependencies = [
"truck-topology",
]
+[[package]]
+name = "solvecraft-mcp"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "solvecraft-engine",
+]
+
[[package]]
name = "solvecraft-render"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 0defcac186..5b4a6bbad0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -20,6 +20,7 @@ solvecraft-doc = { path = "crates/doc" }
solvecraft-io = { path = "crates/io" }
solvecraft-engine = { path = "crates/engine" }
solvecraft-ui-egui = { path = "crates/ui-egui" }
+solvecraft-mcp = { path = "crates/mcp" }
# foundation
thiserror = "2"
diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.toml
new file mode 100644
index 0000000000..bfaaf378f2
--- /dev/null
+++ b/crates/mcp/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "solvecraft-mcp"
+description = "SolveCraft MCP server: JSON-RPC 2.0 over stdio, driving a headless session or the running app"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+solvecraft-engine = { workspace = true }
+serde_json = { workspace = true }
diff --git a/crates/mcp/src/backend.rs b/crates/mcp/src/backend.rs
new file mode 100644
index 0000000000..98c67401aa
--- /dev/null
+++ b/crates/mcp/src/backend.rs
@@ -0,0 +1,173 @@
+//! Where MCP tool calls end up: a control-channel method call (`docs/control-protocol.md`).
+
+use std::io::{BufRead, BufReader, Read, Write};
+use std::net::{TcpStream, ToSocketAddrs};
+use std::time::Duration;
+
+use serde_json::{Value, json};
+use solvecraft_engine::Session;
+use solvecraft_engine::render::{StandardView, render_png};
+
+/// Something that answers control-channel methods: `engine.execute`, `engine.commands`,
+/// `document.inspect`, `ui.view`, `ui.render`, `ui.screenshot`.
+pub trait Backend {
+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String>;
+ /// True when a real window is attached (`ui.screenshot` can capture it).
+ fn has_ui(&self) -> bool;
+ fn describe(&self) -> String;
+}
+
+/// Longest reply line accepted from the app.
+const MAX_REPLY: u64 = 64 << 20;
+
+/// A running SolveCraft app reached through its loopback control port
+/// (`solvecraft --control PORT`).
+pub struct Remote {
+ addr: String,
+ conn: Option<(BufReader<TcpStream>, TcpStream)>,
+ next_id: u64,
+}
+
+impl Remote {
+ pub fn connect(addr: &str) -> std::io::Result<Self> {
+ let mut r = Self { addr: addr.to_string(), conn: None, next_id: 1 };
+ r.reconnect()?;
+ Ok(r)
+ }
+
+ fn reconnect(&mut self) -> std::io::Result<()> {
+ self.conn = None;
+ let mut last = std::io::Error::new(std::io::ErrorKind::NotFound, format!("cannot resolve {}", self.addr));
+ for sa in self.addr.to_socket_addrs()? {
+ match TcpStream::connect_timeout(&sa, Duration::from_millis(800)) {
+ Ok(s) => {
+ s.set_nodelay(true).ok();
+ // Kernel operations (booleans, fillets) on big parts can take a while.
+ s.set_read_timeout(Some(Duration::from_secs(300))).ok();
+ let read = s.try_clone()?;
+ self.conn = Some((BufReader::new(read), s));
+ return Ok(());
+ }
+ Err(e) => last = e,
+ }
+ }
+ Err(last)
+ }
+
+ fn roundtrip(&mut self, line: &str) -> std::io::Result<String> {
+ if self.conn.is_none() {
+ self.reconnect()?;
+ }
+ let Some((reader, writer)) = self.conn.as_mut() else { return Err(std::io::Error::other("not connected")) };
+ let sent = writer.write_all(line.as_bytes()).and_then(|()| writer.write_all(b"\n")).and_then(|()| writer.flush());
+ if let Err(e) = sent {
+ self.conn = None;
+ return Err(e);
+ }
+ let mut reply = String::new();
+ let n = match reader.by_ref().take(MAX_REPLY).read_line(&mut reply) {
+ Ok(n) => n,
+ Err(e) => {
+ // A timed-out read leaves a late reply on the stream: start afresh next time.
+ self.conn = None;
+ return Err(e);
+ }
+ };
+ if n == 0 || !reply.ends_with('\n') {
+ self.conn = None;
+ return Err(std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "connection closed"));
+ }
+ Ok(reply)
+ }
+}
+
+impl Backend for Remote {
+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {
+ let id = self.next_id;
+ self.next_id += 1;
+ let line = json!({"id": id, "method": method, "params": params}).to_string();
+ let reply = match self.roundtrip(&line) {
+ Ok(r) => r,
+ // One retry on a fresh connection (the app may have restarted).
+ Err(_) => self.roundtrip(&line).map_err(|e| format!("SolveCraft at {}: {e}", self.addr))?,
+ };
+ let v: Value = serde_json::from_str(&reply).map_err(|e| format!("bad reply from the app: {e}"))?;
+ if v.get("ok").and_then(Value::as_bool) == Some(true) {
+ Ok(v.get("result").cloned().unwrap_or(Value::Null))
+ } else {
+ Err(v.get("error").and_then(Value::as_str).unwrap_or("error").to_string())
+ }
+ }
+ fn has_ui(&self) -> bool {
+ true
+ }
+ fn describe(&self) -> String {
+ format!("connected to the SolveCraft app at {} (the user watches the viewport)", self.addr)
+ }
+}
+
+/// An in-process headless session (no window); renders with the CPU rasterizer.
+pub struct Headless {
+ pub session: Session,
+ /// Orientation for renders; the camera is refitted to the model every time.
+ pub view: StandardView,
+}
+
+impl Default for Headless {
+ fn default() -> Self {
+ Headless::new(Session::default())
+ }
+}
+
+impl Headless {
+ pub fn new(session: Session) -> Self {
+ Headless { session, view: StandardView::Iso }
+ }
+}
+
+fn dim(p: &Value, k: &str, default: f64) -> usize {
+ p.get(k).and_then(Value::as_f64).filter(|x| x.is_finite()).unwrap_or(default).clamp(16.0, 4096.0) as usize
+}
+
+impl Backend for Headless {
+ fn call(&mut self, method: &str, p: Value) -> Result<Value, String> {
+ let s = &mut self.session;
+ let str_p = |k: &str| p.get(k).and_then(Value::as_str);
+ match method {
+ "engine.execute" | "command" => {
+ let id = str_p("command").ok_or("missing `command`")?;
+ let params = p.get("params").cloned().filter(|v| !v.is_null()).unwrap_or(json!({}));
+ s.execute(id, &params).map_err(|e| e.to_string())
+ }
+ "engine.script" => s.run_script(&p).map(Value::from).map_err(|e| e.to_string()),
+ "engine.commands" => s.execute("engine.commands", &json!({})).map_err(|e| e.to_string()),
+ "document.inspect" => s.execute("document.inspect", &p).map_err(|e| e.to_string()),
+ "ui.view" => {
+ let v = str_p("view").unwrap_or("home");
+ self.view = match v {
+ "fit" => self.view,
+ _ => StandardView::parse(v).ok_or_else(|| format!("unknown view `{v}`"))?,
+ };
+ Ok(json!({"view": self.view}))
+ }
+ "ui.render" => {
+ let (w, h) = (dim(&p, "width", 1280.0), dim(&p, "height", 800.0));
+ let mut cam = solvecraft_engine::view::home_camera(s);
+ cam.set_view(self.view);
+ let scene = solvecraft_engine::view::scene(s, &cam);
+ let png = render_png(&scene, &cam, w, h).ok_or("render failed")?;
+ let path = str_p("path").ok_or("missing `path`")?;
+ std::fs::write(path, &png).map_err(|e| format!("{path}: {e}"))?;
+ Ok(json!({"path": path, "bytes": png.len(), "width": w, "height": h}))
+ }
+ "ui.screenshot" => Err("no window in headless mode; use ui.render".into()),
+ other => Err(format!("unknown method `{other}`")),
+ }
+ }
+ fn has_ui(&self) -> bool {
+ false
+ }
+ fn describe(&self) -> String {
+ "headless in-process SolveCraft session".into()
+ }
+}
diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rs
new file mode 100644
index 0000000000..3fdc47405b
--- /dev/null
+++ b/crates/mcp/src/lib.rs
@@ -0,0 +1,21 @@
+//! SolveCraft MCP server.
+//!
+//! JSON-RPC 2.0 over stdio (newline-delimited), implementing the MCP lifecycle, tools and
+//! resources. Tools map onto the control-channel methods (`engine.execute`, `document.inspect`,
+//! `ui.render`…, see `docs/control-protocol.md`), served either by an in-process headless
+//! [`Headless`] session or by a running app through its loopback control port ([`Remote`]), so a
+//! person can watch the agent model. Every modelling step is an engine command; tools never open
+//! dialogs.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+#![forbid(unsafe_code)]
+
+mod backend;
+mod server;
+mod tools;
+
+pub use backend::{Backend, Headless, Remote};
+pub use server::{PROTOCOL_VERSION, SUPPORTED_VERSIONS, Server};
+pub use tools::{call_tool, tool_definitions};
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rs
new file mode 100644
index 0000000000..c96defdbf1
--- /dev/null
+++ b/crates/mcp/src/server.rs
@@ -0,0 +1,170 @@
+//! JSON-RPC 2.0 framing and the MCP lifecycle / tools / resources methods.
+
+use std::io::{BufRead, Write};
+
+use serde_json::{Value, json};
+
+use crate::backend::Backend;
+use crate::tools::{call_tool, check_arguments, tool_definitions};
+
+/// The newest protocol revision we speak; offered when the client asks for one we don't know.
+pub const PROTOCOL_VERSION: &str = "2025-06-18";
+pub const SUPPORTED_VERSIONS: &[&str] = &[PROTOCOL_VERSION, "2025-03-26", "2024-11-05"];
+
+const PARSE_ERROR: i64 = -32700;
+const INVALID_REQUEST: i64 = -32600;
+const METHOD_NOT_FOUND: i64 = -32601;
+const INVALID_PARAMS: i64 = -32602;
+const INTERNAL_ERROR: i64 = -32603;
+const RESOURCE_NOT_FOUND: i64 = -32002;
+
+/// Longest accepted request line (a guard against runaway input).
+const MAX_LINE: usize = 16 << 20;
+/// Most messages in one JSON-RPC batch.
+const MAX_BATCH: usize = 1000;
+
+const INSTRUCTIONS: &str = "SolveCraft is a parametric 3D CAD app in the style of Autodesk Fusion. Units are millimetres \
+and degrees in expressions (internally radians), Z is up. Model like in Fusion: `SketchCreate {plane: XY}`, draw \
+(`ShapeRectangleTwoPoint {p0, p1}`, `CircleCenterRadius {center, radius}`, `DrawPolyline {points, closed}`), constrain \
+and dimension (`SketchDimension {entities, value}`; values may name parameters), `SketchStop`, then features \
+(`Extrude {distance, operation?: new|join|cut|intersect}`, `Revolve`, `FusionFilletEdgesCommand {edges: [[x,y,z] point on \
+edge], radius}`, `FusionChamferCommand`, patterns, mirror, primitives). Use `batch` for several steps at once, \
+`list_commands` for ids and parameter docs, `inspect_design` / `measure` to verify, `list_edges` to find edge points, \
+`set_parameter` to drive the design and `screenshot` to look at it.";
+
+pub struct Server {
+ backend: Box<dyn Backend>,
+ initialized: bool,
+}
+
+fn response(id: Value, result: Value) -> Value {
+ json!({"jsonrpc": "2.0", "id": id, "result": result})
+}
+fn error(id: Value, code: i64, message: impl Into<String>) -> Value {
+ json!({"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message.into()}})
+}
+
+impl Server {
+ pub fn new(backend: Box<dyn Backend>) -> Self {
+ Self { backend, initialized: false }
+ }
+ pub fn backend(&mut self) -> &mut dyn Backend {
+ self.backend.as_mut()
+ }
+ pub fn is_initialized(&self) -> bool {
+ self.initialized
+ }
+
+ /// Serve newline-delimited JSON-RPC until `input` closes. Only protocol messages go to
+ /// `output`; diagnostics belong on stderr.
+ pub fn serve(&mut self, input: impl BufRead, mut output: impl Write) -> std::io::Result<()> {
+ for line in input.lines() {
+ let line = match line {
+ Ok(l) => l,
+ // Not UTF-8: answer with a parse error and keep serving.
+ Err(e) if e.kind() == std::io::ErrorKind::InvalidData => {
+ let reply = error(Value::Null, PARSE_ERROR, "parse error: input is not UTF-8").to_string();
+ output.write_all(reply.as_bytes())?;
+ output.write_all(b"\n")?;
+ output.flush()?;
+ continue;
+ }
+ Err(e) => return Err(e),
+ };
+ if let Some(reply) = self.handle_line(&line) {
+ output.write_all(reply.as_bytes())?;
+ output.write_all(b"\n")?;
+ output.flush()?;
+ }
+ }
+ Ok(())
+ }
+
+ /// One line in, at most one line out (notifications get no reply).
+ pub fn handle_line(&mut self, line: &str) -> Option<String> {
+ let line = line.trim();
+ if line.is_empty() {
+ return None;
+ }
+ if line.len() > MAX_LINE {
+ return Some(error(Value::Null, INVALID_REQUEST, "request too large").to_string());
+ }
+ let reply = match serde_json::from_str::<Value>(line) {
+ Ok(Value::Array(batch)) if batch.is_empty() => Some(error(Value::Null, INVALID_REQUEST, "empty batch")),
+ Ok(Value::Array(batch)) if batch.len() > MAX_BATCH => Some(error(Value::Null, INVALID_REQUEST, "batch too large")),
+ Ok(Value::Array(batch)) => {
+ let replies: Vec<Value> = batch.into_iter().filter_map(|m| self.handle(m)).collect();
+ (!replies.is_empty()).then_some(Value::Array(replies))
+ }
+ Ok(msg) => self.handle(msg),
+ Err(e) => Some(error(Value::Null, PARSE_ERROR, format!("parse error: {e}"))),
+ };
+ reply.map(|r| r.to_string())
+ }
+
+ pub fn handle(&mut self, msg: Value) -> Option<Value> {
+ let Value::Object(o) = &msg else { return Some(error(Value::Null, INVALID_REQUEST, "message must be an object")) };
+ let id = o.get("id").cloned();
+ let Some(method) = o.get("method").and_then(Value::as_str) else {
+ // A response to a request of ours (we send none) or junk.
+ if o.contains_key("result") || o.contains_key("error") {
+ return None;
+ }
+ return Some(error(id.unwrap_or(Value::Null), INVALID_REQUEST, "missing `method`"));
+ };
+ let params = o.get("params").cloned().unwrap_or(Value::Null);
+ let Some(id) = id else {
+ if method == "notifications/initialized" {
+ self.initialized = true;
+ }
+ return None;
+ };
+ Some(match self.request(method, &params) {
+ Ok(r) => response(id, r),
+ Err((code, m)) => error(id, code, m),
+ })
+ }
+
+ fn request(&mut self, method: &str, params: &Value) -> Result<Value, (i64, String)> {
+ match method {
+ "initialize" => {
+ let asked = params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL_VERSION);
+ let version = if SUPPORTED_VERSIONS.contains(&asked) { asked } else { PROTOCOL_VERSION };
+ Ok(json!({
+ "protocolVersion": version,
+ "capabilities": {"tools": {"listChanged": false}, "resources": {"listChanged": false}},
+ "serverInfo": {"name": "solvecraft", "title": "SolveCraft", "version": env!("CARGO_PKG_VERSION")},
+ "instructions": format!("{INSTRUCTIONS} Backend: {}.", self.backend.describe()),
+ }))
+ }
+ "ping" => Ok(json!({})),
+ "tools/list" => Ok(json!({"tools": tool_definitions()})),
+ "tools/call" => {
+ let name = params.get("name").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing tool `name`".to_string()))?;
+ let args = match params.get("arguments") {
+ None | Some(Value::Null) => json!({}),
+ Some(a) => a.clone(),
+ };
+ check_arguments(name, &args).map_err(|e| (INVALID_PARAMS, e))?;
+ Ok(call_tool(self.backend.as_mut(), name, &args))
+ }
+ "resources/list" => Ok(json!({"resources": [
+ {"uri": "solvecraft://design", "name": "Active design", "description": "document.inspect with measurements", "mimeType": "application/json"},
+ {"uri": "solvecraft://commands", "name": "Command catalog", "description": "every command with its parameter docs", "mimeType": "application/json"},
+ ]})),
+ "resources/templates/list" => Ok(json!({"resourceTemplates": []})),
+ "prompts/list" => Ok(json!({"prompts": []})),
+ "resources/read" => {
+ let uri = params.get("uri").and_then(Value::as_str).unwrap_or("");
+ let v = match uri {
+ "solvecraft://design" => self.backend.call("document.inspect", json!({"measure": true})),
+ "solvecraft://commands" => self.backend.call("engine.commands", json!({})),
+ _ => return Err((RESOURCE_NOT_FOUND, format!("unknown resource `{uri}`"))),
+ }
+ .map_err(|e| (INTERNAL_ERROR, e))?;
+ Ok(json!({"contents": [{"uri": uri, "mimeType": "application/json", "text": v.to_string()}]}))
+ }
+ _ => Err((METHOD_NOT_FOUND, format!("method `{method}` not found"))),
+ }
+ }
+}
diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs
new file mode 100644
index 0000000000..76798e3127
--- /dev/null
+++ b/crates/mcp/src/tests.rs
@@ -0,0 +1,315 @@
+//! An agent builds parts through MCP only and verifies them through MCP only.
+
+use std::f64::consts::PI;
+
+use serde_json::{Value, json};
+
+use crate::{Headless, PROTOCOL_VERSION, Server, tool_definitions};
+
+fn server() -> Server {
+ Server::new(Box::new(Headless::default()))
+}
+
+fn call(s: &mut Server, id: u64, method: &str, params: Value) -> Value {
+ let line = json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}).to_string();
+ let r = s.handle_line(&line).expect("reply");
+ serde_json::from_str(&r).unwrap()
+}
+
+fn raw_tool(s: &mut Server, name: &str, args: Value) -> Value {
+ call(s, 99, "tools/call", json!({"name": name, "arguments": args}))
+}
+
+/// Call a tool that must succeed; returns its JSON text (or the first content block).
+fn tool(s: &mut Server, name: &str, args: Value) -> Value {
+ let r = raw_tool(s, name, args);
+ let c = &r["result"]["content"][0];
+ assert_ne!(r["result"]["isError"], json!(true), "{name} failed: {c}");
+ assert!(r.get("error").is_none(), "{name}: {r}");
+ if c["type"] == "text" { serde_json::from_str(c["text"].as_str().unwrap()).unwrap_or(Value::Null) } else { c.clone() }
+}
+
+fn volume(s: &mut Server) -> f64 {
+ tool(s, "measure", json!({}))["total"]["volume_mm3"].as_f64().unwrap()
+}
+
+fn rel(a: f64, b: f64) -> f64 {
+ (a - b).abs() / b.abs().max(1e-12)
+}
+
+#[test]
+fn handshake_and_tools_list() {
+ let mut s = server();
+ let init =
+ call(&mut s, 1, "initialize", json!({"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "t", "version": "0"}}));
+ assert_eq!(init["result"]["protocolVersion"], "2025-03-26");
+ assert_eq!(init["result"]["serverInfo"]["name"], "solvecraft");
+ assert!(init["result"]["capabilities"]["tools"].is_object());
+ assert!(init["result"]["instructions"].as_str().unwrap().contains("headless"));
+ // An unknown version gets ours.
+ let init = call(&mut s, 2, "initialize", json!({"protocolVersion": "1999-01-01"}));
+ assert_eq!(init["result"]["protocolVersion"], PROTOCOL_VERSION);
+ assert!(s.handle_line(r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#).is_none());
+ assert!(s.is_initialized());
+ assert_eq!(call(&mut s, 3, "ping", json!({}))["result"], json!({}));
+
+ let tools = call(&mut s, 4, "tools/list", json!({}));
+ let names: Vec<&str> = tools["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap()).collect();
+ for want in [
+ "list_commands",
+ "execute",
+ "batch",
+ "inspect_design",
+ "measure",
+ "body_topology",
+ "set_parameter",
+ "screenshot",
+ "export",
+ "undo",
+ "redo",
+ "new_design",
+ "open",
+ "save",
+ ] {
+ assert!(names.contains(&want), "{want} missing from {names:?}");
+ }
+ for t in tools["result"]["tools"].as_array().unwrap() {
+ assert_eq!(t["inputSchema"]["type"], "object", "{t}");
+ assert!(t["description"].as_str().unwrap().len() > 20, "{t}");
+ }
+
+ let cmds = tool(&mut s, "list_commands", json!({"filter": "fillet"}));
+ assert!(cmds.as_array().unwrap().iter().any(|c| c["id"] == "FusionFilletEdgesCommand"), "{cmds}");
+ assert!(cmds.as_array().unwrap().len() < 5);
+
+ let res = call(&mut s, 5, "resources/list", json!({}));
+ assert_eq!(res["result"]["resources"].as_array().unwrap().len(), 2);
+ let d = call(&mut s, 6, "resources/read", json!({"uri": "solvecraft://design"}));
+ assert!(d["result"]["contents"][0]["text"].as_str().unwrap().contains("timeline"));
+ assert_eq!(call(&mut s, 7, "resources/read", json!({"uri": "solvecraft://nope"}))["error"]["code"], -32002);
+ assert_eq!(call(&mut s, 8, "nope/nope", json!({}))["error"]["code"], -32601);
+}
+
+/// Box → fillet → hole in one batch, then verify with measure / inspect_design and look at it.
+#[test]
+fn agent_builds_box_fillet_hole() {
+ let mut s = server();
+ let r = tool(
+ &mut s,
+ "batch",
+ json!({"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"}},
+ ]}),
+ );
+ assert_eq!(r["completed"], 8, "{r}");
+ let expect = 24000.0 - (9.0 - PI * 9.0 / 4.0) * 20.0 - PI * 25.0 * 20.0;
+ let v = volume(&mut s);
+ assert!(rel(v, expect) < 5e-4, "{v} vs {expect}");
+ let m = tool(&mut s, "measure", json!({"body": "Body1"}));
+ // 6 box faces + fillet + hole wall (the kernel may keep the wall as two halves).
+ assert!((8..=9).contains(&m["bodies"][0]["faces"].as_u64().unwrap()), "{m}");
+ assert!(rel(m["bodies"][0]["bbox"]["max"][0].as_f64().unwrap(), 40.0) < 1e-6, "{m}");
+
+ let d = tool(&mut s, "inspect_design", json!({}));
+ assert_eq!(d["timeline"].as_array().unwrap().len(), 5, "{d}");
+ assert!(d["timeline"].as_array().unwrap().iter().all(|f| f["error"].is_null()), "{d}");
+ assert_eq!(d["sketches"][0]["curves"].as_array().unwrap().len(), 4, "{d}");
+ assert!(d["sketches"][0]["status"].is_string(), "{d}");
+ assert!(d["bodies"][0]["volume_mm3"].as_f64().unwrap() > 0.0);
+
+ let topo = tool(&mut s, "body_topology", json!({"body": "Body1"}));
+ assert!(topo["edges"].as_array().unwrap().len() >= 12, "{topo}");
+ assert!(topo["faces"].as_array().unwrap().len() >= 8, "{topo}");
+
+ // Undo the hole, redo it.
+ tool(&mut s, "undo", json!({}));
+ assert!(rel(volume(&mut s), 24000.0 - (9.0 - PI * 9.0 / 4.0) * 20.0) < 5e-4);
+ tool(&mut s, "redo", json!({}));
+ assert!(rel(volume(&mut s), expect) < 5e-4);
+
+ // Look at it from the top: a real PNG comes back as an image block.
+ let img = tool(&mut s, "screenshot", json!({"view": "top", "width": 320, "height": 200}));
+ assert_eq!(img["type"], "image");
+ assert_eq!(img["mimeType"], "image/png");
+ assert!(img["data"].as_str().unwrap().starts_with("iVBORw0KGgo"), "not a PNG");
+
+ // Export, save, start over, open.
+ let dir = std::env::temp_dir().join(format!("solvecraft-mcp-test-{}", std::process::id()));
+ std::fs::create_dir_all(&dir).unwrap();
+ let step = dir.join("part.step");
+ tool(&mut s, "export", json!({"path": step.to_string_lossy()}));
+ assert!(std::fs::read_to_string(&step).unwrap().contains("ISO-10303-21"));
+ let stl = dir.join("part.stl");
+ tool(&mut s, "export", json!({"path": stl.to_string_lossy(), "format": "stl"}));
+ assert!(std::fs::metadata(&stl).unwrap().len() > 1000);
+ let shot = dir.join("shot.png");
+ tool(&mut s, "screenshot", json!({"path": shot.to_string_lossy(), "width": 64, "height": 64}));
+ assert!(std::fs::metadata(&shot).unwrap().len() > 100);
+ let design = dir.join("part.solvecraft");
+ tool(&mut s, "save", json!({"path": design.to_string_lossy()}));
+ tool(&mut s, "new_design", json!({"name": "Empty"}));
+ assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 0);
+ tool(&mut s, "open", json!({"path": design.to_string_lossy()}));
+ assert!(rel(volume(&mut s), expect) < 5e-4);
+ let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn parameters_drive_the_design() {
+ let mut s = server();
+ tool(&mut s, "set_parameter", json!({"name": "len", "value": "40 mm"}));
+ tool(&mut s, "execute", json!({"command": "PrimitiveBox", "params": {"length": "len", "width": 30, "height": "len / 2", "corner": [0, 0, 0]}}));
+ assert!(rel(volume(&mut s), 40.0 * 30.0 * 20.0) < 1e-9);
+ let r = tool(&mut s, "set_parameter", json!({"name": "len", "value": 50}));
+ assert_eq!(r["value"], 50.0, "{r}");
+ assert_eq!(r["errors"].as_array().unwrap().len(), 0, "{r}");
+ assert!(rel(volume(&mut s), 50.0 * 30.0 * 25.0) < 1e-9);
+ let d = tool(&mut s, "inspect_design", json!({"measure": false, "sketches": false}));
+ assert!(d["params"].as_array().unwrap().iter().any(|p| p["name"] == "len" && p["value"] == 50.0), "{d}");
+}
+
+#[test]
+fn batch_stops_at_first_error_and_rolls_back() {
+ let mut s = server();
+ tool(&mut s, "execute", json!({"command": "PrimitiveBox", "params": {"length": 10, "width": 10, "height": 10}}));
+ let r = raw_tool(
+ &mut s,
+ "batch",
+ json!({"commands": [
+ {"command": "PrimitiveSphere", "params": {"radius": 3, "center": [50, 0, 0]}},
+ {"command": "Extrude", "params": {"distance": "bogus +"}},
+ {"command": "PrimitiveSphere", "params": {"radius": 3, "center": [80, 0, 0]}},
+ ]}),
+ );
+ assert_eq!(r["result"]["isError"], true, "{r}");
+ let body: Value = serde_json::from_str(r["result"]["content"][0]["text"].as_str().unwrap()).unwrap();
+ assert_eq!(body["failed"]["index"], 1, "{body}");
+ assert_eq!(body["failed"]["command"], "Extrude");
+ assert_eq!(body["undone"], 1, "{body}");
+ assert_eq!(body["results"].as_array().unwrap().len(), 1);
+ // Only the first box is left, and its undo step is intact.
+ assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 1);
+ assert_eq!(tool(&mut s, "inspect_design", json!({"measure": false}))["undo"], 1);
+
+ // Without rollback the completed steps stay.
+ let r = raw_tool(
+ &mut s,
+ "batch",
+ json!({"rollback": false, "commands": [{"command": "PrimitiveSphere", "params": {"radius": 3, "center": [50, 0, 0]}}, {"command": "NoSuchCommand"}]}),
+ );
+ assert_eq!(r["result"]["isError"], true);
+ assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("NoSuchCommand"));
+ assert_eq!(tool(&mut s, "measure", json!({}))["body_count"], 2);
+}
+
+#[test]
+fn unknown_tools_and_bad_arguments_are_clean_errors() {
+ let mut s = server();
+ let r = raw_tool(&mut s, "make_coffee", json!({}));
+ assert_eq!(r["error"]["code"], -32602, "{r}");
+ assert!(r["error"]["message"].as_str().unwrap().contains("make_coffee"));
+ assert_eq!(raw_tool(&mut s, "execute", json!({}))["error"]["code"], -32602);
+ assert_eq!(raw_tool(&mut s, "execute", json!({"command": 5}))["error"]["code"], -32602);
+ assert_eq!(raw_tool(&mut s, "measure", json!({"bogus": 1}))["error"]["code"], -32602);
+ assert_eq!(raw_tool(&mut s, "screenshot", json!({"view": "sideways"}))["error"]["code"], -32602);
+ assert_eq!(call(&mut s, 1, "tools/call", json!({"arguments": {}}))["error"]["code"], -32602);
+ // Engine errors are tool errors the model can read.
+ let r = raw_tool(&mut s, "execute", json!({"command": "Extrude", "params": {"distance": 10}}));
+ assert_eq!(r["result"]["isError"], true, "{r}");
+ let r = raw_tool(&mut s, "execute", json!({"command": "NoSuchCommand"}));
+ assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("unknown command"));
+ // Framing errors.
+ assert!(s.handle_line("{not json").unwrap().contains("-32700"));
+ assert!(s.handle_line("[]").unwrap().contains("-32600"));
+ assert!(s.handle_line("42").unwrap().contains("-32600"));
+ assert!(s.handle_line(" ").is_none());
+ assert!(s.handle_line(r#"{"jsonrpc":"2.0","id":1,"result":{}}"#).is_none());
+ let both = s.handle_line(r#"[{"jsonrpc":"2.0","id":1,"method":"ping"},{"jsonrpc":"2.0","method":"notifications/x"}]"#).unwrap();
+ assert_eq!(serde_json::from_str::<Value>(&both).unwrap().as_array().unwrap().len(), 1);
+}
+
+fn hostile_values() -> Vec<Value> {
+ vec![
+ Value::Null,
+ json!(true),
+ json!(-1),
+ json!(0),
+ json!(1e308),
+ json!(-1e308),
+ json!(""),
+ json!("nope"),
+ json!("../../../../../../nonexistent/dir/x.step"),
+ json!("1/0"),
+ json!([]),
+ json!([1e308, -1e308]),
+ json!([{"command": "Extrude", "params": {"distance": 1e308}}]),
+ json!([{"command": 7}, null, "x"]),
+ json!({}),
+ json!({"x": 1}),
+ ]
+}
+
+/// Every tool, every argument it documents, every hostile value: replies are well-formed
+/// JSON-RPC and nothing panics.
+#[test]
+fn hostile_arguments_never_panic() {
+ let mut s = server();
+ tool(&mut s, "execute", json!({"command": "PrimitiveBox", "params": {"length": 10, "width": 10, "height": 10}}));
+ let defs = tool_definitions();
+ let mut n = 0;
+ for def in &defs {
+ let name = def["name"].as_str().unwrap();
+ // Hostile strings are relative paths: don't let the sweep write files into the crate.
+ let writes = matches!(name, "save" | "screenshot" | "export");
+ let keys: Vec<String> = def["inputSchema"]["properties"].as_object().unwrap().keys().filter(|k| !(writes && *k == "path")).cloned().collect();
+ for k in &keys {
+ for v in hostile_values() {
+ let mut args = json!({});
+ // Fill the other required arguments with something plausible.
+ for r in def["inputSchema"]["required"].as_array().into_iter().flatten() {
+ args[r.as_str().unwrap()] = json!("Body1");
+ }
+ args[k.as_str()] = v;
+ if name == "screenshot" && (k == "width" || k == "height") {
+ args["view"] = json!("front");
+ }
+ let r = raw_tool(&mut s, name, args.clone());
+ assert!(r.get("result").is_some() || r["error"]["code"].is_i64(), "{name} {args}: {r}");
+ n += 1;
+ }
+ }
+ }
+ assert!(n > 100);
+ // Execute every command with hostile params through MCP too.
+ let cmds = tool(&mut s, "list_commands", json!({}));
+ for c in cmds.as_array().unwrap() {
+ let id = c["id"].as_str().unwrap();
+ if matches!(id, "doc.open" | "SaveDocumentCommand" | "SaveDocumentAsCommand" | "ExportCommand" | "FusionSaveAsSTLCommand") {
+ continue;
+ }
+ for v in hostile_values() {
+ let r = raw_tool(&mut s, "execute", json!({"command": id, "params": {"distance": v.clone(), "edges": v.clone(), "plane": v}}));
+ assert!(r.get("result").is_some(), "{id}: {r}");
+ }
+ }
+ // Arguments that are not an object.
+ for v in hostile_values().into_iter().filter(|v| !v.is_object() && !v.is_null()) {
+ let r = call(&mut s, 1, "tools/call", json!({"name": "measure", "arguments": v}));
+ assert_eq!(r["error"]["code"], -32602, "{r}");
+ }
+}
+
+#[test]
+fn base64_matches_rfc4648() {
+ use crate::tools::base64;
+ for (i, o) in [("", ""), ("f", "Zg=="), ("fo", "Zm8="), ("foo", "Zm9v"), ("foob", "Zm9vYg=="), ("fooba", "Zm9vYmE="), ("foobar", "Zm9vYmFy")] {
+ assert_eq!(base64(i.as_bytes()), o);
+ }
+}
diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs
new file mode 100644
index 0000000000..365ee14e15
--- /dev/null
+++ b/crates/mcp/src/tools.rs
@@ -0,0 +1,481 @@
+//! MCP tool definitions and dispatch. Every tool is a thin wrapper over engine commands
+//! (`engine.execute`) and the inspection / rendering control methods.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use serde_json::{Map, Value, json};
+
+use crate::backend::Backend;
+
+/// Most commands in one `batch` call.
+const MAX_BATCH: usize = 10_000;
+/// Largest image returned by `screenshot`.
+const MAX_IMAGE_BYTES: u64 = 32 << 20;
+
+const VIEWS: &[&str] = &["iso", "home", "front", "back", "top", "bottom", "left", "right", "fit"];
+
+fn obj(props: Value, required: &[&str]) -> Value {
+ let mut o = json!({"type": "object", "properties": props, "additionalProperties": false});
+ if !required.is_empty() {
+ o["required"] = json!(required);
+ }
+ o
+}
+
+fn tool(name: &str, title: &str, desc: &str, schema: Value, read_only: bool, destructive: bool) -> Value {
+ json!({
+ "name": name,
+ "title": title,
+ "description": desc,
+ "inputSchema": schema,
+ "annotations": {"title": title, "readOnlyHint": read_only, "destructiveHint": destructive, "idempotentHint": read_only, "openWorldHint": false},
+ })
+}
+
+fn string(desc: &str) -> Value {
+ json!({"type": "string", "description": desc})
+}
+
+/// Every tool, with its JSON schema. The same list serves the headless and the bridged backend.
+pub fn tool_definitions() -> Vec<Value> {
+ vec![
+ tool(
+ "list_commands",
+ "List commands",
+ "The command catalog: id, label, toolbar tab/panel, shortcut, one-line parameter docs and whether the command is \
+ enabled right now. Ids are Fusion's command ids where Fusion has the command (Extrude, SketchCreate, \
+ FusionFilletEdgesCommand…), dotted ids otherwise (sketch.inspect, timeline.rollback). Optional case-insensitive \
+ substring `filter` over id, label, panel and params.",
+ obj(json!({"filter": string("Substring to match, e.g. \"sketch\", \"fillet\", \"pattern\"")}), &[]),
+ true,
+ false,
+ ),
+ tool(
+ "execute",
+ "Execute a command",
+ "Run one command with JSON parameters, exactly as the toolbar, palette and scripts do. Never opens a dialog. \
+ Examples: SketchCreate {plane: \"XY\"}; ShapeRectangleTwoPoint {p0: [0,0], p1: [40,30]}; CircleCenterRadius \
+ {center: [20,15], radius: 5}; SketchDimension {entities: [curve id], value: \"width\"}; SketchStop {}; Extrude \
+ {distance: 20, operation: \"cut\"}; FusionFilletEdgesCommand {edges: [[0,0,10]], radius: 3}; PrimitiveBox {length, \
+ width, height}. Lengths are mm; expressions may use parameters and units (\"width / 2\", \"30 deg\"). Returns \
+ the command's result; failures leave the design unchanged.",
+ obj(
+ json!({
+ "command": string("Command id (see list_commands)"),
+ "params": {"type": "object", "description": "The command's parameters"},
+ }),
+ &["command"],
+ ),
+ false,
+ false,
+ ),
+ tool(
+ "batch",
+ "Run several commands",
+ "Run commands in order, stopping at the first error. Each step is {command, params}. On an error the steps \
+ already run are undone (unless rollback: false), so the batch is all-or-nothing; the reply names the failing \
+ step (index from 0), its error, and every result before it. The usual way to build a part: sketch, draw, \
+ dimension, finish, extrude, fillet… in one call.",
+ obj(
+ json!({
+ "commands": {
+ "type": "array",
+ "description": "Steps: [{\"command\": id, \"params\": {...}}, ...]",
+ "items": {"type": "object", "properties": {"command": {"type": "string"}, "params": {"type": "object"}}, "required": ["command"]},
+ },
+ "rollback": {"type": "boolean", "description": "Undo completed steps when one fails (default true)"},
+ }),
+ &["commands"],
+ ),
+ false,
+ false,
+ ),
+ tool(
+ "inspect_design",
+ "Inspect the design",
+ "The whole design: user parameters (expression, value, errors), the timeline (features with type, suppressed, \
+ rolled back, error, warning, timing), bodies (volume, area, centre of mass, bounding box, face/edge/vertex \
+ counts), sketches (curves with ids and coordinates, points, constraints, profiles, degrees of freedom, solve \
+ status), the active sketch, selection and undo depth.",
+ obj(
+ json!({
+ "measure": {"type": "boolean", "description": "Measure bodies (default true)"},
+ "sketches": {"type": "boolean", "description": "Full sketch contents (default true; false = summary only)"},
+ }),
+ &[],
+ ),
+ true,
+ false,
+ ),
+ tool(
+ "measure",
+ "Measure bodies",
+ "Volume (mm³), surface area (mm²), centre of mass, bounding box and face/edge/vertex counts of one body or all \
+ bodies, with totals.",
+ obj(json!({"body": string("Body name (default: all bodies)")}), &[]),
+ true,
+ false,
+ ),
+ tool(
+ "body_topology",
+ "List edges and faces",
+ "The edges (index, midpoint, length, endpoints) and faces (index, area, centroid, plane normal) of a body. Use \
+ an edge midpoint as the [x,y,z] point that picks the edge for fillet and chamfer.",
+ obj(json!({"body": string("Body name, e.g. \"Body1\"")}), &["body"]),
+ true,
+ false,
+ ),
+ tool(
+ "set_parameter",
+ "Set a parameter",
+ "Create or change a user parameter and re-evaluate the timeline. `value` is a number (mm) or an expression \
+ (\"40 mm\", \"width * 2\", \"30 deg\"). Returns the new value, the features recomputed and any features that now fail.",
+ obj(
+ json!({
+ "name": string("Parameter name"),
+ "value": {"type": ["number", "string"], "description": "Number or expression"},
+ "unit": string("mm, deg or \"\" (unitless); default from the expression"),
+ "comment": string("Comment shown in the parameters table"),
+ }),
+ &["name", "value"],
+ ),
+ false,
+ false,
+ ),
+ tool(
+ "screenshot",
+ "Look at the design",
+ "Render the design and return it as a PNG image. Headless: a CPU render of the model, fitted to the view. \
+ Connected to the app: a screenshot of the window (source \"window\", the default) or a render of the model \
+ with the app's camera (source \"model\"). `view` first turns the camera to a standard view.",
+ obj(
+ json!({
+ "view": {"type": "string", "enum": VIEWS, "description": "Standard view (default: keep the current one; headless starts at iso)"},
+ "path": string("Also keep the PNG at this path"),
+ "width": {"type": "integer", "description": "Render width in pixels (model renders; default 960)"},
+ "height": {"type": "integer", "description": "Render height in pixels (model renders; default 600)"},
+ "source": {"type": "string", "enum": ["window", "model"], "description": "window = app screenshot, model = model render"},
+ }),
+ &[],
+ ),
+ true,
+ false,
+ ),
+ tool(
+ "export",
+ "Export",
+ "Export bodies to STEP (.step/.stp), binary STL (.stl), ASCII STL (format stla) or OBJ. The format comes from \
+ the extension unless given.",
+ obj(
+ json!({
+ "path": string("Output file"),
+ "format": {"type": "string", "enum": ["step", "stl", "stla", "obj"]},
+ "bodies": {"type": "array", "items": {"type": "string"}, "description": "Body names (default: all)"},
+ }),
+ &["path"],
+ ),
+ false,
+ false,
+ ),
+ tool("undo", "Undo", "Undo the last change to the design.", obj(json!({}), &[]), false, false),
+ tool("redo", "Redo", "Redo the last undone change.", obj(json!({}), &[]), false, false),
+ tool(
+ "new_design",
+ "New design",
+ "Start a new, empty design (unsaved changes to the current one are discarded).",
+ obj(json!({"name": string("Design name (default Untitled)")}), &[]),
+ false,
+ true,
+ ),
+ tool(
+ "open",
+ "Open a design",
+ "Open a .solvecraft design file (replaces the current design).",
+ obj(json!({"path": string("Path to a .solvecraft file")}), &["path"]),
+ false,
+ true,
+ ),
+ tool(
+ "save",
+ "Save the design",
+ "Save the design as a .solvecraft file (to `path`, or to the file it came from).",
+ obj(json!({"path": string("Path to save to (default: the current file)")}), &[]),
+ false,
+ false,
+ ),
+ ]
+}
+
+fn type_matches(t: &str, v: &Value) -> bool {
+ match t {
+ "string" => v.is_string(),
+ "number" => v.is_number(),
+ "integer" => v.is_i64() || v.is_u64(),
+ "boolean" => v.is_boolean(),
+ "array" => v.is_array(),
+ "object" => v.is_object(),
+ "null" => v.is_null(),
+ _ => true,
+ }
+}
+
+/// Validates `args` against the tool's schema (top level): unknown tool, missing required
+/// arguments, unknown arguments, type and enum mismatches.
+pub(crate) fn check_arguments(name: &str, args: &Value) -> Result<(), String> {
+ let defs = tool_definitions();
+ let def = defs.iter().find(|d| d["name"] == name).ok_or_else(|| format!("unknown tool `{name}`"))?;
+ let schema = &def["inputSchema"];
+ let Some(a) = args.as_object() else { return Err(format!("{name}: arguments must be an object")) };
+ for r in schema["required"].as_array().into_iter().flatten().filter_map(Value::as_str) {
+ if a.get(r).is_none_or(Value::is_null) {
+ return Err(format!("{name}: missing required argument `{r}`"));
+ }
+ }
+ let props = schema["properties"].as_object();
+ for (k, v) in a {
+ let Some(p) = props.and_then(|p| p.get(k)) else {
+ return Err(format!("{name}: unknown argument `{k}`"));
+ };
+ if v.is_null() {
+ continue;
+ }
+ let ok = match &p["type"] {
+ Value::String(t) => type_matches(t, v),
+ Value::Array(ts) => ts.iter().filter_map(Value::as_str).any(|t| type_matches(t, v)),
+ _ => true,
+ };
+ if !ok {
+ return Err(format!("{name}: argument `{k}` must be of type {}", p["type"]));
+ }
+ if let Some(allowed) = p["enum"].as_array()
+ && !allowed.contains(v)
+ {
+ return Err(format!("{name}: `{k}` must be one of {}", Value::Array(allowed.clone())));
+ }
+ }
+ Ok(())
+}
+
+/// A tool result: content blocks plus the error flag.
+fn text_result(v: &Value, is_error: bool) -> Value {
+ let text = match v {
+ Value::String(s) => s.clone(),
+ v => serde_json::to_string_pretty(v).unwrap_or_default(),
+ };
+ let mut r = json!({"content": [{"type": "text", "text": text}]});
+ if is_error {
+ r["isError"] = json!(true);
+ }
+ r
+}
+
+/// Run a tool. Failures are tool results with `isError: true` (the model sees the message);
+/// nothing here panics on hostile arguments.
+pub fn call_tool(b: &mut dyn Backend, name: &str, args: &Value) -> Value {
+ let empty = Map::new();
+ let a = args.as_object().unwrap_or(&empty);
+ let r = match name {
+ "screenshot" => return screenshot(b, a),
+ "batch" => return batch(b, a),
+ _ => dispatch(b, name, a),
+ };
+ match r {
+ Ok(v) => text_result(&v, false),
+ Err(e) => text_result(&Value::String(e), true),
+ }
+}
+
+fn exec(b: &mut dyn Backend, command: &str, params: Value) -> Result<Value, String> {
+ b.call("engine.execute", json!({"command": command, "params": params}))
+}
+
+fn pick(a: &Map<String, Value>, keys: &[&str]) -> Value {
+ Value::Object(keys.iter().filter_map(|k| a.get(*k).filter(|v| !v.is_null()).map(|v| (k.to_string(), v.clone()))).collect())
+}
+
+fn str_arg<'a>(a: &'a Map<String, Value>, k: &str) -> Option<&'a str> {
+ a.get(k).and_then(Value::as_str)
+}
+
+fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<Value, String> {
+ match name {
+ "list_commands" => {
+ let all = b.call("engine.commands", json!({}))?;
+ let Some(f) = str_arg(a, "filter").map(str::to_lowercase).filter(|f| !f.is_empty()) else { return Ok(all) };
+ let hit = |c: &Value| {
+ ["id", "label", "panel", "tab", "params"]
+ .iter()
+ .any(|k| c.get(*k).and_then(Value::as_str).is_some_and(|s| s.to_lowercase().contains(&f)))
+ };
+ Ok(Value::Array(all.as_array().map(|v| v.iter().filter(|c| hit(c)).cloned().collect()).unwrap_or_default()))
+ }
+ "execute" => {
+ let id = str_arg(a, "command").ok_or("`command` is required")?;
+ exec(b, id, a.get("params").cloned().filter(Value::is_object).unwrap_or(json!({})))
+ }
+ "inspect_design" => {
+ let measure = a.get("measure").and_then(Value::as_bool).unwrap_or(true);
+ let mut d = b.call("document.inspect", json!({"measure": measure}))?;
+ if a.get("sketches").and_then(Value::as_bool).unwrap_or(true) {
+ let ids: Vec<Value> = d["sketches"].as_array().map(|v| v.iter().map(|s| s["id"].clone()).collect()).unwrap_or_default();
+ let full: Vec<Value> = ids
+ .into_iter()
+ .map(|id| exec(b, "sketch.inspect", json!({"sketch": id.clone()})).unwrap_or_else(|e| json!({"id": id, "error": e})))
+ .collect();
+ d["sketches"] = Value::Array(full);
+ }
+ Ok(d)
+ }
+ "measure" => {
+ let p = match str_arg(a, "body") {
+ Some(body) => json!({"bodies": [body]}),
+ None => json!({}),
+ };
+ exec(b, "MeasureCommand", p)
+ }
+ "body_topology" => {
+ let p = pick(a, &["body"]);
+ let edges = exec(b, "model.edges", p.clone())?;
+ let faces = exec(b, "model.faces", p)?;
+ Ok(json!({"body": a.get("body"), "edges": edges["edges"], "faces": faces["faces"]}))
+ }
+ "set_parameter" => {
+ let mut p = pick(a, &["name", "unit", "comment"]);
+ p["expression"] = a.get("value").cloned().unwrap_or(Value::Null);
+ exec(b, "ChangeParameterCommand", p)
+ }
+ "export" => exec(b, "ExportCommand", pick(a, &["path", "format", "bodies"])),
+ "undo" => exec(b, "UndoCommand", json!({})),
+ "redo" => exec(b, "RedoCommand", json!({})),
+ "new_design" => exec(b, "NewDocumentCommand", pick(a, &["name"])),
+ "open" => exec(b, "doc.open", pick(a, &["path"])),
+ "save" => exec(b, "SaveDocumentCommand", pick(a, &["path"])),
+ other => Err(format!("unknown tool `{other}`")),
+ }
+}
+
+fn undo_depth(b: &mut dyn Backend) -> Option<u64> {
+ b.call("document.inspect", json!({})).ok().and_then(|d| d["undo"].as_u64())
+}
+
+/// `batch`: run steps in order, stop at the first failure and (by default) undo what ran.
+fn batch(b: &mut dyn Backend, a: &Map<String, Value>) -> Value {
+ let Some(steps) = a.get("commands").and_then(Value::as_array) else {
+ return text_result(&json!("`commands` must be an array of {command, params}"), true);
+ };
+ if steps.len() > MAX_BATCH {
+ return text_result(&json!(format!("batch too long ({} steps, at most {MAX_BATCH})", steps.len())), true);
+ }
+ let rollback = a.get("rollback").and_then(Value::as_bool).unwrap_or(true);
+ let before = if rollback { undo_depth(b) } else { None };
+ let mut results = Vec::with_capacity(steps.len());
+ for (i, step) in steps.iter().enumerate() {
+ let command = step.get("command").or_else(|| step.get("id")).and_then(Value::as_str);
+ let r = match command {
+ Some(id) => exec(b, id, step.get("params").cloned().filter(|p| !p.is_null()).unwrap_or(json!({}))),
+ None => Err("missing `command`".to_string()),
+ };
+ match r {
+ Ok(v) => results.push(v),
+ Err(e) => {
+ let mut undone = 0u64;
+ if let (Some(before), Some(after)) = (before, rollback.then(|| undo_depth(b)).flatten()) {
+ for _ in before..after {
+ if exec(b, "UndoCommand", json!({})).is_err() {
+ break;
+ }
+ undone += 1;
+ }
+ }
+ return text_result(
+ &json!({
+ "ok": false,
+ "completed": i,
+ "failed": {"index": i, "command": command, "error": e},
+ "rolled_back": rollback,
+ "undone": undone,
+ "results": results,
+ }),
+ true,
+ );
+ }
+ }
+ }
+ text_result(&json!({"ok": true, "completed": results.len(), "results": results}), false)
+}
+
+static SHOT: AtomicU64 = AtomicU64::new(0);
+
+/// `screenshot`: render or capture to a file, return it as an MCP image content block.
+fn screenshot(b: &mut dyn Backend, a: &Map<String, Value>) -> Value {
+ match capture(b, a) {
+ Ok((png, info)) => json!({"content": [
+ {"type": "image", "data": base64(&png), "mimeType": "image/png"},
+ {"type": "text", "text": info.to_string()},
+ ]}),
+ Err(e) => text_result(&Value::String(e), true),
+ }
+}
+
+fn capture(b: &mut dyn Backend, a: &Map<String, Value>) -> Result<(Vec<u8>, Value), String> {
+ if let Some(v) = str_arg(a, "view") {
+ b.call("ui.view", json!({"view": v}))?;
+ // Turning to a standard view also frames the model (like a view cube click).
+ if v != "fit" && v != "home" {
+ b.call("ui.view", json!({"view": "fit"}))?;
+ }
+ }
+ let keep = str_arg(a, "path").filter(|p| !p.trim().is_empty()).map(str::to_string);
+ let path = keep.clone().unwrap_or_else(|| {
+ let n = SHOT.fetch_add(1, Ordering::Relaxed);
+ std::env::temp_dir().join(format!("solvecraft-mcp-{}-{n}.png", std::process::id())).to_string_lossy().to_string()
+ });
+ let window = match str_arg(a, "source") {
+ Some("model") => false,
+ Some("window") => true,
+ _ => b.has_ui(),
+ };
+ let size = |k: &str, d: u64| a.get(k).and_then(Value::as_u64).unwrap_or(d).clamp(16, 4096);
+ let render = |b: &mut dyn Backend| b.call("ui.render", json!({"path": path, "width": size("width", 960), "height": size("height", 600)}));
+ let (info, source) = if window {
+ match b.call("ui.screenshot", json!({"path": path})) {
+ Ok(v) => (v, "window"),
+ // No presented frame (minimised or hidden window): fall back to a model render.
+ Err(_) => (render(b)?, "model"),
+ }
+ } else {
+ (render(b)?, "model")
+ };
+ let read = std::fs::metadata(&path)
+ .map_err(|e| format!("{path}: {e}"))
+ .and_then(|m| if m.len() > MAX_IMAGE_BYTES { Err(format!("{path}: image too large")) } else { Ok(()) })
+ .and_then(|()| std::fs::read(&path).map_err(|e| format!("{path}: {e} (is the app on another machine?)")));
+ if keep.is_none() {
+ let _ = std::fs::remove_file(&path);
+ }
+ let png = read?;
+ let (w, h) = match source {
+ "model" => (json!(size("width", 960)), json!(size("height", 600))),
+ _ => (info.get("width").cloned().unwrap_or(Value::Null), info.get("height").cloned().unwrap_or(Value::Null)),
+ };
+ let bytes = png.len();
+ Ok((png, json!({"source": source, "path": keep, "width": w, "height": h, "bytes": bytes})))
+}
+
+/// Standard base64 with padding (RFC 4648).
+pub(crate) fn base64(data: &[u8]) -> String {
+ const T: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+ let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
+ for chunk in data.chunks(3) {
+ let b = [chunk.first().copied().unwrap_or(0), chunk.get(1).copied().unwrap_or(0), chunk.get(2).copied().unwrap_or(0)];
+ let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
+ for (i, shift) in [18u32, 12, 6, 0].into_iter().enumerate() {
+ if i <= chunk.len() {
+ out.push(char::from(T[((n >> shift) & 63) as usize]));
+ } else {
+ out.push('=');
+ }
+ }
+ }
+ out
+}
diff --git a/xtask/src/layers.rs b/xtask/src/layers.rs
index 7d1252d4f2..c381629ef5 100644
--- a/xtask/src/layers.rs
+++ b/xtask/src/layers.rs
@@ -43,6 +43,7 @@ pub const TABLE: &[(&str, Class)] = &[
("io", Class::Layer(3)),
("engine", Class::Layer(4)),
("ui-egui", Class::Layer(5)),
+ ("mcp", Class::Layer(5)),
("testkit", Class::Testkit),
// apps and tooling
("solvecraft", Class::Exempt),