DesignCraft: An open-source page and layout design editor written by scratch in pure Rust
M1.9: MCP server (designcraft-mcp) + designcraft-cli mcp
Brandon Thomas044534503cd1
diff --git a/Cargo.lock b/Cargo.lockindex d373ce949..0d70b5ec9 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -758,6 +758,7 @@ version = "0.1.0"dependencies = ["designcraft-doc","designcraft-engine",+ "designcraft-mcp","designcraft-render","serde_json",]@@ -836,6 +837,19 @@ dependencies = ["thiserror 2.0.21",]+[[package]]+name = "designcraft-mcp"+version = "0.1.0"+dependencies = [+ "designcraft-engine",+ "designcraft-geom",+ "designcraft-render",+ "designcraft-tools",+ "image",+ "log",+ "serde_json",+]+[[package]]name = "designcraft-render"version = "0.1.0"diff --git a/ROADMAP.md b/ROADMAP.mdindex 14206957e..91fa7dd2d 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -11,8 +11,9 @@ DesignCraft aims at full Adobe InDesign parity — and to be better: faster, ope- UI (egui): application bar + menus, Control panel (object and text modes), Tools panel with flyouts, document tabs, rulers, pasteboard, guides (margins, columns, bleed, baseline grid), frame edges, selection handles, text ports and threads, Properties / Pages / Layers dock, Swatches, Styles, Character, Paragraph, Stroke, Text Wrap panels, New Document dialog, ⌘K palette, 4 brightness themes.- Tools: Selection (click, marquee, move, Alt-duplicate, resize handles), Direct Selection (basic), Type (draw frame, click caret, select, type), Rectangle/Ellipse/Polygon (+ frame variants), Line, Hand, Zoom.- ~100 commands, all reachable through the JSON control channel; headless CLI rendering to PNG.+- MCP server (`designcraft-cli mcp [--connect PORT]`, docs/mcp.md): headless engine or the running app; commands, batch, document/story inspection, page renders as images, window screenshots, pointer/keyboard/dialog input.-**Next (in order):** MCP server · PDF export (krilla, PDF/X-4) · IDML import/export · native format as zip · web build · Pen tool & Direct Selection anchors · Story Editor · Find/Change (+GREP) · tables · Liang hyphenation · smart guides · Links panel + relink · Preflight · TOC/index/footnotes · EPUB.+**Next (in order):** PDF export (krilla, PDF/X-4) · IDML import/export · native format as zip · web build · Pen tool & Direct Selection anchors · Story Editor · Find/Change (+GREP) · tables · Liang hyphenation · smart guides · Links panel + relink · Preflight · TOC/index/footnotes · EPUB.## Milestonesdiff --git a/apps/designcraft-cli/Cargo.toml b/apps/designcraft-cli/Cargo.tomlindex 51b78bb2f..e354a1b80 100644--- a/apps/designcraft-cli/Cargo.toml+++ b/apps/designcraft-cli/Cargo.toml@@ -16,4 +16,5 @@ path = "src/main.rs"designcraft-engine = { workspace = true }designcraft-render = { workspace = true }designcraft-doc = { workspace = true }+designcraft-mcp = { workspace = true }serde_json = { workspace = true }diff --git a/apps/designcraft-cli/src/main.rs b/apps/designcraft-cli/src/main.rsindex 03977eedb..7f09bf540 100644--- a/apps/designcraft-cli/src/main.rs+++ b/apps/designcraft-cli/src/main.rs@@ -3,7 +3,7 @@//! ```text//! designcraft-cli run [--in FILE | --sample] [--cmd ID[=JSON]]... [--page N] [--scale S] [--export OUT.png|.jpg|.designcraft] [--all-pages DIR]//! designcraft-cli commands # list every command (JSON)-//! designcraft-cli mcp [--connect PORT] # MCP server over stdio+//! designcraft-cli mcp [--connect PORT] [--sample] # MCP server over stdio (docs/mcp.md)//! ```use std::process::ExitCode;@@ -22,7 +22,7 @@ fn main() -> ExitCode {Some("mcp") => report(mcp(&args[1..])),_ => {eprintln!(- "usage: designcraft-cli run [--in FILE | --sample] [--cmd ID[=JSON]]... [--page N] [--scale S] [--export OUT] [--all-pages DIR]\n designcraft-cli commands\n designcraft-cli mcp [--connect PORT]"+ "usage: designcraft-cli run [--in FILE | --sample] [--cmd ID[=JSON]]... [--page N] [--scale S] [--export OUT] [--all-pages DIR]\n designcraft-cli commands\n designcraft-cli mcp [--connect PORT] [--sample]");ExitCode::FAILURE}@@ -39,8 +39,40 @@ fn report(r: Result<(), String>) -> ExitCode {}}-fn mcp(_args: &[String]) -> Result<(), String> {- Err("the MCP server lands with the designcraft-mcp crate".into())+/// `mcp` (headless, in-process engine) or `mcp --connect PORT|HOST:PORT` (drive a running app+/// started with `designcraft --control PORT`). JSON-RPC on stdin/stdout; logs on stderr.+fn mcp(args: &[String]) -> Result<(), String> {+ use designcraft_mcp::{Backend, Headless, Remote, Server, control_addr};+ let mut connect: Option<String> = None;+ let mut sample = false;+ let mut it = args.iter();+ while let Some(a) = it.next() {+ match a.as_str() {+ "--connect" => connect = Some(it.next().cloned().ok_or("--connect needs a port or host:port")?),+ "--sample" => sample = true,+ other => return Err(format!("unknown mcp option `{other}` (usage: designcraft-cli mcp [--connect PORT] [--sample])")),+ }+ }+ let backend: Box<dyn Backend> = match connect {+ Some(c) => {+ let addr = control_addr(&c);+ Box::new(+ Remote::connect(&addr)+ .map_err(|e| format!("cannot connect to the DesignCraft app at {addr}: {e} (start it with `designcraft --control PORT`)"))?,+ )+ }+ None => {+ let mut h = Headless::with_document();+ if sample {+ h.session.execute("file.newSample", &json!({})).map_err(|e| e.to_string())?;+ }+ Box::new(h)+ }+ };+ eprintln!("designcraft-cli: MCP server on stdio ({})", backend.describe());+ let stdin = std::io::stdin();+ let stdout = std::io::stdout();+ Server::new(backend).serve(stdin.lock(), stdout.lock()).map_err(|e| e.to_string())}fn run(args: &[String]) -> Result<(), String> {diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.tomlnew file mode 100644index 000000000..fa863aa94--- /dev/null+++ b/crates/mcp/Cargo.toml@@ -0,0 +1,20 @@+[package]+name = "designcraft-mcp"+version.workspace = true+edition.workspace = true+license.workspace = true+description = "DesignCraft MCP server: JSON-RPC 2.0 over stdio, driving a running app or a headless session"++[lints]+workspace = true++[dependencies]+designcraft-engine = { workspace = true }+designcraft-render = { workspace = true }+designcraft-tools = { workspace = true }+designcraft-geom = { workspace = true }+serde_json = { workspace = true }+log = { workspace = true }++[dev-dependencies]+image = { workspace = true }diff --git a/crates/mcp/src/backend.rs b/crates/mcp/src/backend.rsnew file mode 100644index 000000000..0b940aa3a--- /dev/null+++ b/crates/mcp/src/backend.rs@@ -0,0 +1,107 @@+//! Where MCP tool calls end up: a control-channel method call.++use std::io::{BufRead, BufReader, Write};+use std::net::{TcpStream, ToSocketAddrs};+use std::time::Duration;++use serde_json::{Value, json};++/// Something that answers control-channel methods (`engine.execute`, `document.inspect`,+/// `ui.pointer`, `ui.render`, …). See `designcraft_ui_egui::control` for the full list.+pub trait Backend {+ /// Call one method. `Ok` carries the `result`, `Err` the error message.+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String>;+ /// True when a real UI is attached (`ui.screenshot`, `ui.click`, dialogs… work).+ fn has_ui(&self) -> bool;+ /// Short human description ("headless", "connected to 127.0.0.1:7979").+ fn describe(&self) -> String;+}++/// A running DesignCraft app, reached through its loopback control port.+pub struct Remote {+ addr: String,+ conn: Option<(BufReader<TcpStream>, TcpStream)>,+ next_id: u64,+}++impl Remote {+ /// Connect to `addr` (`127.0.0.1:7979`), failing fast when nothing is listening.+ 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)+ }++ pub fn addr(&self) -> &str {+ &self.addr+ }++ 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();+ // The app answers within 60 s (its own timeout); leave headroom.+ s.set_read_timeout(Some(Duration::from_secs(90))).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::new(std::io::ErrorKind::NotConnected, "not connected"));+ };+ writer.write_all(line.as_bytes())?;+ writer.write_all(b"\n")?;+ writer.flush()?;+ let mut reply = String::new();+ if reader.read_line(&mut reply)? == 0 {+ return Err(std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "control channel 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();+ // One retry with a fresh connection (the app may have restarted).+ let reply = match self.roundtrip(&line) {+ Ok(r) => r,+ Err(_) => {+ self.conn = None;+ self.roundtrip(&line).map_err(|e| {+ self.conn = None;+ format!("DesignCraft app at {} is not reachable: {e}", self.addr)+ })?+ }+ };+ let v: Value = serde_json::from_str(reply.trim()).map_err(|e| format!("bad reply from 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("unknown error").to_string())+ }+ }++ fn has_ui(&self) -> bool {+ true+ }++ fn describe(&self) -> String {+ format!("connected to the DesignCraft app at {}", self.addr)+ }+}diff --git a/crates/mcp/src/headless.rs b/crates/mcp/src/headless.rsnew file mode 100644index 000000000..87bec33cb--- /dev/null+++ b/crates/mcp/src/headless.rs@@ -0,0 +1,265 @@+//! An in-process engine session that answers the engine-level control-channel methods itself.++use designcraft_engine::{Session, ViewInfo};+use designcraft_geom::Point;+use designcraft_render::{RenderOptions, Renderer};+use designcraft_tools::{Mods, PointerEvent, PointerKind, TOOL_GROUPS, ToolKey};+use serde_json::{Value, json};++use crate::backend::Backend;++/// Headless backend: a [`Session`] plus a CPU [`Renderer`] for page renders and PNG export.+pub struct Headless {+ pub session: Session,+ pub renderer: Renderer,+}++impl Default for Headless {+ fn default() -> Self {+ Self::new()+ }+}++/// Hint appended to errors for methods that need a window.+pub(crate) const NEEDS_APP: &str = "it needs the desktop app: start `designcraft --control 7979` and run the MCP server \+with `designcraft-cli mcp --connect 7979`";++const VIEW: ViewInfo = ViewInfo { zoom: 1.0 };++fn s<'a>(p: &'a Value, k: &str) -> Option<&'a str> {+ p.get(k).and_then(Value::as_str)+}++pub(crate) fn pointer_kind(k: &str) -> Option<PointerKind> {+ Some(match k {+ "down" => PointerKind::Down,+ "drag" => PointerKind::Drag,+ "up" => PointerKind::Up,+ "move" => PointerKind::Move,+ "doubleclick" | "dblclick" => PointerKind::DoubleClick,+ _ => return None,+ })+}++fn tool_key(name: &str) -> Option<ToolKey> {+ Some(match name.to_ascii_lowercase().as_str() {+ "enter" | "return" => ToolKey::Enter,+ "esc" | "escape" => ToolKey::Escape,+ "backspace" => ToolKey::Backspace,+ "delete" => ToolKey::Delete,+ "up" | "arrowup" => ToolKey::Up,+ "down" | "arrowdown" => ToolKey::Down,+ "left" | "arrowleft" => ToolKey::Left,+ "right" | "arrowright" => ToolKey::Right,+ "home" => ToolKey::Home,+ "end" => ToolKey::End,+ "pageup" => ToolKey::PageUp,+ "pagedown" => ToolKey::PageDown,+ "tab" => ToolKey::Tab,+ _ => return None,+ })+}++/// Does a shortcut like `Cmd+Shift+]` match `key` + `mods`?+fn shortcut_matches(shortcut: &str, key: &str, mods: Mods) -> bool {+ let parts: Vec<&str> = shortcut.split('+').collect();+ // "Cmd+=": the last part is the key even if it's punctuation; "Cmd++" would split oddly but+ // no shortcut uses it.+ let Some((k, ms)) = parts.split_last() else { return false };+ let has = |m: &str| ms.iter().any(|x| x.eq_ignore_ascii_case(m));+ k.eq_ignore_ascii_case(key)+ && has("cmd") == mods.cmd+ && has("shift") == mods.shift+ && (has("alt") || has("option")) == mods.alt+ && has("ctrl") == mods.ctrl+}++fn mods_from(p: &Value) -> Mods {+ let b = |n: &str| p.get(n).and_then(Value::as_bool).unwrap_or(false);+ Mods { shift: b("shift"), alt: b("alt"), cmd: b("cmd"), ctrl: b("ctrl"), space: false }+}++impl Headless {+ /// A session with no document (the first `file.new` / `file.open` creates one).+ pub fn new() -> Self {+ Self { session: Session::new(), renderer: Renderer::new() }+ }++ /// A session with a fresh default (Letter) document, ready to lay out.+ pub fn with_document() -> Self {+ let mut h = Self::new();+ if let Err(e) = h.session.execute("file.new", &json!({})) {+ log::error!("file.new failed: {e}");+ }+ h+ }++ fn exec(&mut self, id: &str, params: &Value) -> Result<Value, String> {+ let r = self.session.execute(id, params).map_err(|e| {+ let ui_only = ["app.", "view.", "window."].iter().any(|p| id.starts_with(p));+ if ui_only && designcraft_engine::find_command(id).is_none() { format!("`{id}` is a UI command; {NEEDS_APP}") } else { e.to_string() }+ });+ // Requests for a UI (file pickers, dialogs) have nobody to serve them here.+ self.session.ui_requests.clear();+ r+ }++ fn selection(&self) -> Value {+ self.session.active().map(|d| serde_json::to_value(&d.selection).unwrap_or_default()).unwrap_or(Value::Null)+ }++ fn pointer(&mut self, p: &Value) -> Result<Value, String> {+ let events = p.get("events").and_then(Value::as_array).ok_or("missing `events`")?;+ let base: Mods = p.get("mods").and_then(|m| serde_json::from_value(m.clone()).ok()).unwrap_or_default();+ if self.session.active().is_none() {+ return Err("no document open (use new_document first)".into());+ }+ for e in events {+ let kind = s(e, "kind").unwrap_or("");+ let kind = pointer_kind(kind).ok_or_else(|| format!("unknown pointer kind `{kind}` (down|drag|up|move|doubleclick)"))?;+ if s(e, "space") == Some("screen") {+ return Err(format!("screen-space pointer events: {NEEDS_APP}. Use spread coordinates instead"));+ }+ let x = e.get("x").and_then(Value::as_f64).ok_or("pointer event needs numeric `x`")?;+ let y = e.get("y").and_then(Value::as_f64).ok_or("pointer event needs numeric `y`")?;+ let mods = e.get("mods").and_then(|m| serde_json::from_value(m.clone()).ok()).unwrap_or(base);+ self.session.pointer(&PointerEvent { kind, pos: Point::new(x, y), mods }, VIEW).map_err(|e| e.to_string())?;+ }+ let requests: Vec<Value> = self.session.ui_requests.drain(..).map(|r| serde_json::to_value(r).unwrap_or_default()).collect();+ Ok(json!({"selection": self.selection(), "tool": self.session.tool_id(), "requests": requests}))+ }++ /// Keyboard input: the active tool (caret movement, Enter/Tab/Backspace while typing), then+ /// command shortcuts, then tool shortcuts, then plain text while typing.+ fn key(&mut self, p: &Value) -> Result<Value, String> {+ let key = s(p, "key").ok_or("missing `key`")?;+ let mods = mods_from(p);+ let typing = self.session.wants_text();+ let tk = tool_key(key);+ if let Some(k) = tk+ && (typing || self.session.tool_busy())+ && self.session.tool_key(k, mods, VIEW).map_err(|e| e.to_string())?+ {+ self.session.ui_requests.clear();+ return Ok(json!({"handledBy": "tool", "tool": self.session.tool_id(), "selection": self.selection()}));+ }+ // While typing, plain keys are text, not shortcuts.+ let plain = !mods.cmd && !mods.ctrl && !mods.alt;+ if !(typing && plain)+ && let Some(c) = designcraft_engine::command_specs().iter().find(|c| c.shortcut.is_some_and(|sc| shortcut_matches(sc, key, mods)))+ {+ let r = self.exec(c.id, &json!({}))?;+ return Ok(json!({"handledBy": "command", "command": c.id, "result": r}));+ }+ if !typing && let Some(t) = TOOL_GROUPS.iter().flat_map(|g| g.iter()).find(|t| t.shortcut.is_some_and(|sc| shortcut_matches(sc, key, mods))) {+ self.session.set_tool(t.id);+ return Ok(json!({"handledBy": "tool.select", "tool": t.id}));+ }+ if let Some(k) = tk+ && self.session.tool_key(k, mods, VIEW).map_err(|e| e.to_string())?+ {+ self.session.ui_requests.clear();+ return Ok(json!({"handledBy": "tool", "tool": self.session.tool_id(), "selection": self.selection()}));+ }+ if typing && plain {+ let text = s(p, "text").map(str::to_string).or_else(|| {+ let mut c = key.chars();+ match (c.next(), c.next()) {+ (Some(ch), None) => Some(if mods.shift { ch.to_uppercase().collect() } else { ch.to_lowercase().collect() }),+ _ if key.eq_ignore_ascii_case("space") => Some(" ".into()),+ _ => None,+ }+ });+ if let Some(t) = text {+ self.exec("text.insert", &json!({"text": t}))?;+ return Ok(json!({"handledBy": "text", "text": t}));+ }+ }+ Err(format!("key `{key}` does nothing here (no tool, command or tool shortcut bound to it)"))+ }++ fn text(&mut self, p: &Value) -> Result<Value, String> {+ let t = s(p, "text").ok_or("missing `text`")?;+ if !self.session.wants_text() {+ return Err("no text insertion point: click into a text frame with the type tool first (pointer with tool \"type\"), \+ or select text with execute text.select, or use set_story_text"+ .into());+ }+ self.exec("text.insert", &json!({"text": t}))?;+ Ok(json!({"inserted": t.chars().count()}))+ }++ fn render(&mut self, p: &Value) -> Result<Value, String> {+ let st = self.session.active().ok_or("no document open")?;+ let page = p.get("page").and_then(Value::as_u64).unwrap_or(0) as usize;+ let scale = p.get("scale").and_then(Value::as_f64).unwrap_or(1.0).clamp(0.05, 16.0);+ let bleed = p.get("bleed").and_then(Value::as_bool).unwrap_or(false);+ let img = self+ .renderer+ .render_page(&st.doc, &self.session.cache, page, scale, bleed, &RenderOptions { printing_only: true, ..Default::default() })+ .ok_or_else(|| format!("no page {page} (the document has {} pages, indices are 0-based)", st.doc.page_count()))?;+ let png = img.to_png();+ match s(p, "path") {+ Some(path) => {+ std::fs::write(path, &png).map_err(|e| format!("write {path}: {e}"))?;+ Ok(json!({"path": path, "width": img.width, "height": img.height}))+ }+ None => Ok(json!({"width": img.width, "height": img.height, "pngBase64": designcraft_engine::cmd::base64_encode(&png)})),+ }+ }++ /// `app.export {path, page?, scale?}`: PNG (or JPEG by extension) of one page, like the+ /// app's Export Page as PNG.+ fn export(&mut self, p: &Value) -> Result<Value, String> {+ let path = s(p, "path").ok_or("missing `path`")?;+ let st = self.session.active().ok_or("no document open")?;+ let page = p.get("page").and_then(Value::as_u64).unwrap_or(0) as usize;+ let scale = p.get("scale").and_then(Value::as_f64).unwrap_or(2.0).clamp(0.05, 16.0);+ let img = self+ .renderer+ .render_page(&st.doc, &self.session.cache, page, scale, false, &RenderOptions { printing_only: true, ..Default::default() })+ .ok_or_else(|| format!("no page {page}"))?;+ let lower = path.to_ascii_lowercase();+ let bytes = if lower.ends_with(".jpg") || lower.ends_with(".jpeg") { img.to_jpeg(90) } else { img.to_png() };+ std::fs::write(path, &bytes).map_err(|e| format!("write {path}: {e}"))?;+ Ok(json!({"path": path, "width": img.width, "height": img.height}))+ }+}++impl Backend for Headless {+ fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {+ let p = ¶ms;+ match method {+ "engine.execute" | "ui.menu.invoke" | "command" => {+ let id = s(p, "command").or(s(p, "id")).ok_or("missing `command`")?.to_string();+ let params = match p.get("params") {+ None | Some(Value::Null) => json!({}),+ Some(v) => v.clone(),+ };+ self.exec(&id, ¶ms)+ }+ "engine.commands" => Ok(serde_json::to_value(self.session.commands()).unwrap_or_default()),+ "document.inspect" => self.exec("document.inspect", &json!({})),+ "ui.tool.select" => self.exec("tool.select", &json!({"tool": s(p, "tool").unwrap_or("")})),+ "ui.tool.list" => Ok(serde_json::to_value(TOOL_GROUPS).unwrap_or_default()),+ "ui.pointer" => self.pointer(p),+ "ui.key" => self.key(p),+ "ui.text" => self.text(p),+ "ui.render" => self.render(p),+ "app.open" => self.exec("file.open", &json!({"path": s(p, "path")})),+ "app.save" => self.exec("file.save", &json!({"path": s(p, "path")})),+ "app.export" => self.export(p),+ "app.quit" => Ok(Value::Null),+ m if m.starts_with("ui.") => Err(format!("`{m}` is not available headless; {NEEDS_APP}")),+ other => Err(format!("unknown method `{other}`")),+ }+ }++ fn has_ui(&self) -> bool {+ false+ }++ fn describe(&self) -> String {+ "headless (in-process engine, no window)".into()+ }+}diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rsnew file mode 100644index 000000000..01cfed73c--- /dev/null+++ b/crates/mcp/src/lib.rs@@ -0,0 +1,36 @@+//! DesignCraft's MCP server.+//!+//! [Model Context Protocol](https://modelcontextprotocol.io) over stdio: newline-delimited+//! JSON-RPC 2.0, hand-written (no async runtime). The server exposes DesignCraft as a set of MCP+//! tools and resources and forwards everything to a [`Backend`]:+//!+//! - [`Remote`] talks to a running desktop app through its loopback JSON-lines control channel+//! (`designcraft --control 7979`): one `{"id","method","params"}` line in, one+//! `{"id","ok","result"|"error"}` line out (see `docs/control-protocol.md`).+//! - [`Headless`] hosts an in-process [`designcraft_engine::Session`] and implements the+//! engine-level control-channel methods itself (rendering pages with `designcraft-render`), so+//! agents can build layouts and look at them without a window.+//!+//! Entry points: [`Server::serve`] (stdio loop) and [`Server::handle_line`] (one message).+#![forbid(unsafe_code)]++mod backend;+mod headless;+mod server;+mod tools;++pub use backend::{Backend, Remote};+pub use headless::Headless;+pub use server::{PROTOCOL_VERSION, Server};+pub use tools::{ToolResult, call_tool, tool_definitions};++/// Default control-channel port of the desktop app.+pub const DEFAULT_PORT: u16 = 7979;++/// `"7979"` → `"127.0.0.1:7979"`; `"host:port"` is kept as is.+pub fn control_addr(s: &str) -> String {+ if s.parse::<u16>().is_ok() { format!("127.0.0.1:{s}") } else { s.to_string() }+}++#[cfg(test)]+mod tests;diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rsnew file mode 100644index 000000000..9505732af--- /dev/null+++ b/crates/mcp/src/server.rs@@ -0,0 +1,166 @@+//! 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, tool_definitions};++/// The MCP revision we implement.+pub const PROTOCOL_VERSION: &str = "2025-06-18";+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;++const INSTRUCTIONS: &str = "DesignCraft is a page-layout app (an InDesign clone). Coordinates are points in spread \+space (y down; on a single-page spread the page's top-left is (0,0); a default Letter page is 612×792). Every action \+is a command: find ids and parameters with list_commands and run them with execute (or several with batch). Typical \+flow: new_document → execute frame.create {rect:[x0,y0,x1,y1], content:\"text\", text:\"…\"} → set_story_text / \+execute type.char / style.paragraph.apply → render_page to look at the result. inspect_document lists pages, items \+(ids, bounds), stories (overset) and styles. place_image puts a picture on the page.";++/// Resource URIs.+pub const DOC_URI: &str = "designcraft://document";+pub const COMMANDS_URI: &str = "designcraft://commands";++/// An MCP server bound to one backend.+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()+ }++ /// Whether the client has sent `notifications/initialized`.+ pub fn is_initialized(&self) -> bool {+ self.initialized+ }++ /// Serve newline-delimited JSON-RPC until `input` closes. Logs go to stderr only (stdout is+ /// the protocol stream).+ pub fn serve(&mut self, input: impl BufRead, mut output: impl Write) -> std::io::Result<()> {+ for line in input.lines() {+ let line = line?;+ if let Some(reply) = self.handle_line(&line) {+ output.write_all(reply.as_bytes())?;+ output.write_all(b"\n")?;+ output.flush()?;+ }+ }+ Ok(())+ }++ /// Handle one line; returns the reply line (None for notifications and blank lines).+ pub fn handle_line(&mut self, line: &str) -> Option<String> {+ let line = line.trim();+ if line.is_empty() {+ return None;+ }+ let reply = match serde_json::from_str::<Value>(line) {+ Ok(Value::Array(batch)) => {+ // Batches were removed in 2025-06-18; still answer older clients sensibly.+ if batch.is_empty() {+ Some(error(Value::Null, INVALID_REQUEST, "empty batch"))+ } else {+ 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())+ }++ /// Handle one JSON-RPC message; `None` for notifications and responses.+ 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 server→client request (we send none): ignore. Anything else is invalid.+ 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 {+ self.notification(method);+ return None;+ };+ if !(id.is_string() || id.is_number()) {+ return Some(error(Value::Null, INVALID_REQUEST, "`id` must be a string or number"));+ }+ Some(match self.request(method, ¶ms) {+ Ok(r) => response(id, r),+ Err((code, m)) => error(id, code, m),+ })+ }++ fn notification(&mut self, method: &str) {+ match method {+ "notifications/initialized" => self.initialized = true,+ "notifications/cancelled" | "notifications/progress" | "notifications/roots/list_changed" => {}+ other => log::debug!("ignoring notification {other}"),+ }+ }++ 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": {}, "resources": {}},+ "serverInfo": {"name": "designcraft", "title": "DesignCraft", "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 = params.get("arguments").cloned().unwrap_or(Value::Null);+ Ok(call_tool(self.backend.as_mut(), name, &args).to_value())+ }+ "resources/list" => Ok(json!({"resources": [+ {"uri": DOC_URI, "name": "document", "title": "Active document", "description": "Pages, spreads, items, stories, styles, swatches and selection of the active document (document.inspect)", "mimeType": "application/json"},+ {"uri": COMMANDS_URI, "name": "commands", "title": "Commands", "description": "Every command: id, label, menu path, shortcut, params, enabled (engine.commands)", "mimeType": "application/json"},+ ]})),+ "resources/templates/list" => Ok(json!({"resourceTemplates": []})),+ "resources/read" => {+ let uri = params.get("uri").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing `uri`".to_string()))?;+ let v = match uri {+ DOC_URI => self.backend.call("document.inspect", json!({})),+ COMMANDS_URI => self.backend.call("engine.commands", json!({})),+ _ => return Err((RESOURCE_NOT_FOUND, format!("resource not found: {uri}"))),+ }+ .map_err(|e| (INTERNAL_ERROR, e))?;+ Ok(json!({"contents": [{"uri": uri, "mimeType": "application/json", "text": serde_json::to_string_pretty(&v).unwrap_or_default()}]}))+ }+ other => Err((METHOD_NOT_FOUND, format!("method not found: {other}"))),+ }+ }+}diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rsnew file mode 100644index 000000000..63ab741f9--- /dev/null+++ b/crates/mcp/src/tests.rs@@ -0,0 +1,393 @@+use std::io::{BufRead, BufReader, Write};++use designcraft_engine::cmd::{base64_decode, base64_encode};+use serde_json::{Value, json};++use crate::{Backend, Headless, PROTOCOL_VERSION, Remote, Server, control_addr, tool_definitions};++fn server() -> Server {+ Server::new(Box::new(Headless::with_document()))+}++fn rpc(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 reply = s.handle_line(&line).expect("reply");+ let v: Value = serde_json::from_str(&reply).expect("reply is JSON");+ assert_eq!(v["jsonrpc"], "2.0");+ assert_eq!(v["id"], id);+ v+}++fn call(s: &mut Server, name: &str, args: Value) -> Value {+ let v = rpc(s, 99, "tools/call", json!({"name": name, "arguments": args}));+ assert!(v.get("error").is_none(), "{v}");+ v["result"].clone()+}++/// Call a tool that must succeed; returns its JSON text payload.+fn ok(s: &mut Server, name: &str, args: Value) -> Value {+ let r = call(s, name, args);+ assert_eq!(r["isError"], false, "{name}: {r}");+ serde_json::from_str(&text_of(&r)).unwrap_or(Value::Null)+}++fn text_of(result: &Value) -> String {+ result["content"].as_array().unwrap().iter().filter(|c| c["type"] == "text").map(|c| c["text"].as_str().unwrap().to_string()).collect()+}++fn image_of(result: &Value) -> Vec<u8> {+ let img = result["content"].as_array().unwrap().iter().find(|c| c["type"] == "image").expect("image block");+ assert_eq!(img["mimeType"], "image/png");+ base64_decode(img["data"].as_str().unwrap())+}++fn tmp(name: &str) -> std::path::PathBuf {+ let dir = std::env::temp_dir().join(format!("designcraft-mcp-test-{}", std::process::id()));+ std::fs::create_dir_all(&dir).unwrap();+ dir.join(name)+}++const PNG_MAGIC: &[u8] = b"\x89PNG\r\n\x1a\n";++// ---------- protocol ----------++#[test]+fn framing_basics() {+ let mut s = server();+ assert_eq!(s.handle_line(" "), None);+ assert_eq!(s.handle_line(r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#), None);+ assert!(s.is_initialized());+ let v: Value = serde_json::from_str(&s.handle_line("{not json").unwrap()).unwrap();+ assert_eq!(v["error"]["code"], -32700);+ assert_eq!(v["id"], Value::Null);+ let v: Value = serde_json::from_str(&s.handle_line(r#"{"jsonrpc":"2.0","id":"abc","method":"nope"}"#).unwrap()).unwrap();+ assert_eq!(v["error"]["code"], -32601);+ assert_eq!(v["id"], "abc");+ let v: Value = serde_json::from_str(&s.handle_line(r#"{"jsonrpc":"2.0","id":3}"#).unwrap()).unwrap();+ assert_eq!(v["error"]["code"], -32600);+ assert_eq!(s.handle_line(r#"{"jsonrpc":"2.0","id":9,"result":{}}"#), None);+ assert_eq!(rpc(&mut s, 4, "ping", json!({}))["result"], json!({}));+ let v: Value = serde_json::from_str(+ &s.handle_line(r#"[{"jsonrpc":"2.0","id":1,"method":"ping"},{"jsonrpc":"2.0","method":"notifications/initialized"}]"#).unwrap(),+ )+ .unwrap();+ assert_eq!(v.as_array().unwrap().len(), 1);+ // tools/call without a name is a protocol error, not a tool error.+ assert_eq!(rpc(&mut s, 5, "tools/call", json!({}))["error"]["code"], -32602);+}++#[test]+fn protocol_round_trip_over_serve() {+ let mut s = server();+ let input = [+ json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":PROTOCOL_VERSION,"capabilities":{},"clientInfo":{"name":"t","version":"0"}}}),+ json!({"jsonrpc":"2.0","method":"notifications/initialized"}),+ json!({"jsonrpc":"2.0","id":2,"method":"tools/list"}),+ json!({"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_commands","arguments":{"filter":"frame.create"}}}),+ json!({"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"execute","arguments":{"command":"frame.create","params":{"rect":[36,36,300,200],"content":"text","text":"Hi"}}}}),+ json!({"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"designcraft://document"}}),+ ]+ .map(|v| v.to_string())+ .join("\n");+ let mut out = Vec::new();+ s.serve(input.as_bytes(), &mut out).unwrap();+ let lines: Vec<Value> = String::from_utf8(out).unwrap().lines().map(|l| serde_json::from_str(l).unwrap()).collect();+ assert_eq!(lines.len(), 5, "one reply per request, none for the notification");+ assert_eq!(lines[0]["result"]["protocolVersion"], PROTOCOL_VERSION);+ assert_eq!(lines[0]["result"]["serverInfo"]["name"], "designcraft");+ assert!(lines[0]["result"]["capabilities"]["tools"].is_object());+ assert!(lines[0]["result"]["instructions"].as_str().unwrap().contains("headless"));+ let tools = lines[1]["result"]["tools"].as_array().unwrap();+ assert_eq!(tools.len(), tool_definitions().len());+ let listed: Value = serde_json::from_str(&text_of(&lines[2]["result"])).unwrap();+ assert_eq!(listed["count"], 1);+ assert_eq!(listed["commands"][0]["id"], "frame.create");+ let created: Value = serde_json::from_str(&text_of(&lines[3]["result"])).unwrap();+ assert!(created["id"].is_u64() && created["story"].is_u64(), "{created}");+ let doc: Value = serde_json::from_str(lines[4]["result"]["contents"][0]["text"].as_str().unwrap()).unwrap();+ assert_eq!(doc["stories"][0]["preview"], "Hi");+}++#[test]+fn initialize_negotiates_version() {+ let mut s = server();+ let v = rpc(&mut s, 1, "initialize", json!({"protocolVersion": "2024-11-05"}));+ assert_eq!(v["result"]["protocolVersion"], "2024-11-05");+ let v = rpc(&mut s, 2, "initialize", json!({"protocolVersion": "1999-01-01"}));+ assert_eq!(v["result"]["protocolVersion"], PROTOCOL_VERSION);+}++#[test]+fn tool_definitions_are_well_formed() {+ let defs = tool_definitions();+ let mut names = std::collections::HashSet::new();+ for t in &defs {+ let name = t["name"].as_str().unwrap();+ assert!(names.insert(name), "duplicate tool {name}");+ assert!(name.chars().all(|c| c.is_ascii_lowercase() || c == '_'), "{name}");+ assert!(t["description"].as_str().unwrap().len() > 20, "{name} needs a description");+ assert_eq!(t["inputSchema"]["type"], "object", "{name}");+ for r in t["inputSchema"]["required"].as_array().into_iter().flatten() {+ assert!(t["inputSchema"]["properties"].get(r.as_str().unwrap()).is_some(), "{name}: required `{r}` not in properties");+ }+ }+ for want in [+ "list_commands",+ "execute",+ "batch",+ "inspect_document",+ "get_story",+ "set_story_text",+ "new_document",+ "open_document",+ "save_document",+ "render_page",+ "export_png",+ "screenshot",+ "pointer",+ "key",+ "type_text",+ "click",+ "drag",+ "select_tool",+ "menu_list",+ "ui_inspect",+ "dialog_set",+ "dialog_confirm",+ "dialog_cancel",+ "place_image",+ ] {+ assert!(names.contains(want), "missing tool {want}");+ }+ // Every tool is dispatched (no "unknown tool" for listed names).+ let mut s = server();+ for name in names {+ let r = call(&mut s, name, json!({}));+ assert!(!text_of(&r).contains("unknown tool"), "{name} not dispatched");+ }+}++// ---------- layout through the tools ----------++#[test]+fn builds_a_small_layout_and_renders_it() {+ let mut s = server();+ let d = ok(&mut s, "new_document", json!({"width": 400, "height": 300, "margins": 24, "title": "Flyer"}));+ assert_eq!(d["index"], 1);+ let f = ok(&mut s, "execute", json!({"command": "frame.create", "params": {"rect": [24, 24, 376, 150], "content": "text"}}));+ let (frame, story) = (f["id"].as_u64().unwrap(), f["story"].as_u64().unwrap());+ let st = ok(&mut s, "set_story_text", json!({"frame": frame, "text": "Summer Fair\nSaturday in the park"}));+ assert_eq!(st["id"], story);+ assert_eq!(st["paragraphs"], 2);+ ok(&mut s, "execute", json!({"command": "selection.set", "params": {"ids": [frame]}}));+ ok(&mut s, "execute", json!({"command": "type.char", "params": {"size": 28}}));+ let got = ok(&mut s, "get_story", json!({"story": story}));+ assert_eq!(got["text"], "Summer Fair\nSaturday in the park");+ assert!(got["lines"].as_u64().unwrap() >= 2);++ let r = call(&mut s, "render_page", json!({"page": 0, "scale": 1}));+ assert_eq!(r["isError"], false, "{r}");+ let png = image_of(&r);+ assert!(png.starts_with(PNG_MAGIC));+ let info: Value = serde_json::from_str(&text_of(&r)).unwrap();+ assert_eq!((info["width"].as_u64(), info["height"].as_u64()), (Some(400), Some(300)));+ // The page isn't blank: dark text pixels on white paper.+ let img = image::load_from_memory(&png).unwrap().to_rgba8();+ assert_eq!(img.dimensions(), (400, 300));+ assert!(img.pixels().any(|p| p.0[0] < 128 && p.0[3] > 200), "no text was drawn");++ let doc = ok(&mut s, "inspect_document", json!({}));+ assert_eq!(doc["title"], "Flyer");+ assert_eq!(doc["spreads"][0]["items"][0]["id"], frame);+}++#[test]+fn type_tool_gesture_then_typing() {+ let mut s = server();+ let r = ok(+ &mut s,+ "pointer",+ json!({"tool": "type", "events": [{"kind": "down", "x": 72, "y": 72}, {"kind": "drag", "x": 300, "y": 200}, {"kind": "up", "x": 300, "y": 200}]}),+ );+ assert_eq!(r["tool"], "type");+ ok(&mut s, "type_text", json!({"text": "Hello"}));+ ok(&mut s, "key", json!({"key": "Enter"}));+ ok(&mut s, "type_text", json!({"text": "World"}));+ let doc = ok(&mut s, "inspect_document", json!({}));+ let story = doc["stories"][0]["id"].as_u64().unwrap();+ assert_eq!(ok(&mut s, "get_story", json!({"story": story}))["text"], "Hello\nWorld");+ // Escape leaves the text and selects the frame; Cmd+Z undoes through the shortcut.+ let k = ok(&mut s, "key", json!({"key": "Escape"}));+ assert_eq!(k["handledBy"], "tool");+ let k = ok(&mut s, "key", json!({"key": "Z", "cmd": true}));+ assert_eq!(k["command"], "edit.undo");+ // Tool shortcut when not typing.+ assert_eq!(ok(&mut s, "key", json!({"key": "V"}))["tool"], "selection");+}++#[test]+fn batch_stops_on_first_error() {+ let mut s = server();+ let r = call(+ &mut s,+ "batch",+ json!({"commands": [+ {"command": "frame.create", "params": {"rect": [0, 0, 100, 100]}},+ {"command": "no.such.command"},+ {"command": "frame.create", "params": {"rect": [0, 0, 50, 50]}},+ ]}),+ );+ assert_eq!(r["isError"], true);+ let v: Value = serde_json::from_str(&text_of(&r)).unwrap();+ assert_eq!(v["failedIndex"], 1);+ assert_eq!(v["completed"], 1);+ assert!(v["error"].as_str().unwrap().contains("no.such.command"));+ let doc = ok(&mut s, "inspect_document", json!({}));+ assert_eq!(doc["spreads"][0]["items"].as_array().unwrap().len(), 1, "the third command must not run");++ let v = ok(&mut s, "batch", json!({"commands": [{"command": "edit.undo"}, {"command": "document.history"}]}));+ assert_eq!(v["completed"], 2);+}++#[test]+fn ui_only_tools_explain_how_to_connect() {+ let mut s = server();+ for (name, args) in [+ ("screenshot", json!({})),+ ("click", json!({"x": 1, "y": 1})),+ ("drag", json!({"x": 1, "y": 1, "toX": 5, "toY": 5})),+ ("menu_list", json!({})),+ ("ui_inspect", json!({})),+ ("ui_set", json!({"zoom": 2})),+ ("dialog_set", json!({"field": "width", "value": 10})),+ ("dialog_confirm", json!({})),+ ("dialog_cancel", json!({})),+ ] {+ let r = call(&mut s, name, args);+ assert_eq!(r["isError"], true, "{name}");+ assert!(text_of(&r).contains("--connect"), "{name}: {}", text_of(&r));+ }+ let r = call(&mut s, "execute", json!({"command": "view.zoomIn"}));+ assert_eq!(r["isError"], true);+ assert!(text_of(&r).contains("UI command"));+ // Typing without a caret explains what to do.+ let r = call(&mut s, "type_text", json!({"text": "x"}));+ assert_eq!(r["isError"], true);+ assert!(text_of(&r).contains("insertion point"));+}++#[test]+fn files_place_and_export() {+ let mut s = server();+ // A 4×2 red PNG made by the renderer's encoder.+ let px = designcraft_render::Rendered { width: 4, height: 2, pixels: [255, 0, 0, 255].repeat(8) };+ let png = px.to_png();+ let placed = ok(&mut s, "place_image", json!({"base64": base64_encode(&png), "name": "red.png", "x": 50, "y": 60, "width": 100}));+ assert!(placed["id"].is_u64() && placed["asset"].is_u64(), "{placed}");+ let img_path = tmp("red.png");+ std::fs::write(&img_path, &png).unwrap();+ // With a graphic frame selected, Place replaces its content; deselect for a new frame.+ ok(&mut s, "execute", json!({"command": "edit.deselectAll"}));+ assert!(ok(&mut s, "place_image", json!({"path": img_path}))["id"].is_u64());+ assert_eq!(call(&mut s, "place_image", json!({}))["isError"], true);++ let out = tmp("page.png");+ let e = ok(&mut s, "export_png", json!({"path": out, "scale": 0.5}));+ assert_eq!(e["width"], 306);+ assert!(std::fs::read(&out).unwrap().starts_with(PNG_MAGIC));+ let r = call(&mut s, "render_page", json!({"path": tmp("render.png")}));+ assert_eq!(r["isError"], false);+ assert!(std::fs::read(tmp("render.png")).unwrap().starts_with(PNG_MAGIC));++ let doc_path = tmp("saved.designcraft");+ let saved = ok(&mut s, "save_document", json!({"path": doc_path}));+ assert_eq!(saved["path"], doc_path.to_string_lossy().as_ref());+ let opened = ok(&mut s, "open_document", json!({"path": doc_path}));+ assert!(opened["index"].is_u64());+ let doc = ok(&mut s, "inspect_document", json!({}));+ assert_eq!(doc["spreads"][0]["items"].as_array().unwrap().len(), 2);+ assert_eq!(doc["dirty"], false);++ let sample = ok(&mut s, "new_document", json!({"sample": true}));+ assert!(sample["index"].is_u64());+ assert!(ok(&mut s, "inspect_document", json!({}))["pageCount"].as_u64().unwrap() > 1);+ let r = call(&mut s, "render_page", json!({"page": 999}));+ assert_eq!(r["isError"], true);+}++#[test]+fn list_commands_filters() {+ let mut s = server();+ let all = ok(&mut s, "list_commands", json!({}));+ let n = all["count"].as_u64().unwrap();+ assert!(n > 50, "{n}");+ let some = ok(&mut s, "list_commands", json!({"filter": "Arrange"}));+ assert!(some["count"].as_u64().unwrap() >= 4);+ let enabled = ok(&mut s, "list_commands", json!({"enabledOnly": true}));+ assert!(enabled["count"].as_u64().unwrap() < n, "nothing is selected, so some commands are disabled");+ let r = call(&mut s, "nope", json!({}));+ assert_eq!(r["isError"], true);+ assert_eq!(call(&mut s, "execute", json!([1]))["isError"], true);+}++// ---------- connect mode ----------++/// A fake app on a loopback port answering a few control methods, recording what it got.+fn fake_app() -> (String, std::sync::mpsc::Receiver<Value>) {+ let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();+ let addr = listener.local_addr().unwrap().to_string();+ let (tx, rx) = std::sync::mpsc::channel();+ std::thread::spawn(move || {+ let Ok((stream, _)) = listener.accept() else { return };+ let mut out = stream.try_clone().unwrap();+ for line in BufReader::new(stream).lines() {+ let Ok(line) = line else { break };+ let req: Value = serde_json::from_str(&line).unwrap();+ let p = &req["params"];+ let reply = match req["method"].as_str().unwrap() {+ "ui.screenshot" => {+ let px = designcraft_render::Rendered { width: 3, height: 3, pixels: vec![0; 36] };+ std::fs::write(p["path"].as_str().unwrap(), px.to_png()).unwrap();+ json!({"ok": true, "result": {"path": p["path"], "width": 3, "height": 3}})+ }+ "ui.click" => json!({"ok": true, "result": null}),+ "ui.inspect" => json!({"ok": true, "result": {"tool": "selection"}}),+ _ => json!({"ok": false, "error": "nope"}),+ };+ tx.send(req.clone()).unwrap();+ let mut reply = reply;+ reply["id"] = req["id"].clone();+ writeln!(out, "{reply}").unwrap();+ }+ });+ (addr, rx)+}++#[test]+fn connect_mode_forwards_to_the_app() {+ let (addr, seen) = fake_app();+ let remote = Remote::connect(&addr).unwrap();+ assert!(remote.has_ui());+ let mut s = Server::new(Box::new(remote));+ let r = call(&mut s, "screenshot", json!({}));+ assert_eq!(r["isError"], false, "{r}");+ assert!(image_of(&r).starts_with(PNG_MAGIC));+ let got = seen.recv().unwrap();+ assert_eq!(got["method"], "ui.screenshot");+ assert!(!std::path::Path::new(got["params"]["path"].as_str().unwrap()).exists(), "temp screenshot is removed");++ ok(&mut s, "click", json!({"x": 10, "y": 20, "count": 2}));+ let got = seen.recv().unwrap();+ assert_eq!((got["method"].as_str(), got["params"]["x"].as_i64(), got["params"]["count"].as_i64()), (Some("ui.click"), Some(10), Some(2)));+ assert_eq!(ok(&mut s, "ui_inspect", json!({}))["tool"], "selection");+ let r = call(&mut s, "menu_list", json!({}));+ assert_eq!(r["isError"], true);+ assert!(text_of(&r).contains("nope"), "app errors are passed through");+}++#[test]+fn control_addr_accepts_port_or_address() {+ assert_eq!(control_addr("7979"), "127.0.0.1:7979");+ assert_eq!(control_addr("localhost:8000"), "localhost:8000");+ assert!(Remote::connect("127.0.0.1:1").is_err());+}diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rsnew file mode 100644index 000000000..8f4075084--- /dev/null+++ b/crates/mcp/src/tools.rs@@ -0,0 +1,607 @@+//! MCP tool definitions (names, descriptions, JSON Schemas) and their implementations on top of a+//! [`Backend`].++use serde_json::{Map, Value, json};++use crate::backend::Backend;+use crate::headless::NEEDS_APP;++/// The result of `tools/call`: MCP content blocks plus the `isError` flag.+#[derive(Clone, Debug, PartialEq)]+pub struct ToolResult {+ pub content: Vec<Value>,+ pub is_error: bool,+}++impl ToolResult {+ pub fn text(t: impl Into<String>) -> Self {+ Self { content: vec![json!({"type": "text", "text": t.into()})], is_error: false }+ }+ pub fn json(v: &Value) -> Self {+ Self::text(serde_json::to_string_pretty(v).unwrap_or_default())+ }+ pub fn error(t: impl Into<String>) -> Self {+ Self { content: vec![json!({"type": "text", "text": t.into()})], is_error: true }+ }+ /// A PNG image block followed by a JSON text block with details.+ pub fn image(png_base64: String, info: &Value) -> Self {+ Self {+ content: vec![json!({"type": "image", "data": png_base64, "mimeType": "image/png"}), json!({"type": "text", "text": info.to_string()})],+ is_error: false,+ }+ }+ pub fn to_value(&self) -> Value {+ json!({"content": self.content, "isError": self.is_error})+ }+}++// ---------- schemas ----------++fn num(desc: &str) -> Value {+ json!({"type": "number", "description": desc})+}+fn int(desc: &str) -> Value {+ json!({"type": "integer", "minimum": 0, "description": desc})+}+fn string(desc: &str) -> Value {+ json!({"type": "string", "description": desc})+}+fn boolean(desc: &str) -> Value {+ json!({"type": "boolean", "description": desc})+}+fn params_schema() -> Value {+ json!({"type": "object", "description": "Command parameters (see the `params` field of list_commands)"})+}+fn mods_schema() -> Value {+ json!({+ "type": "object",+ "description": "Modifier keys held (cmd = Command on macOS / Ctrl elsewhere; alt = Option)",+ "properties": {"shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}, "ctrl": {"type": "boolean"}},+ "additionalProperties": false+ })+}+fn obj(props: Value, required: &[&str]) -> Value {+ let mut o = json!({"type": "object", "properties": props});+ if !required.is_empty() {+ o["required"] = json!(required);+ }+ o+}+fn tool(name: &str, title: &str, desc: &str, schema: Value, read_only: bool) -> Value {+ json!({+ "name": name,+ "title": title,+ "description": desc,+ "inputSchema": schema,+ "annotations": {"title": title, "readOnlyHint": read_only, "openWorldHint": false},+ })+}++const APP_ONLY: &str = " Desktop app only (`designcraft-cli mcp --connect PORT`).";++/// All tools, in `tools/list` order.+pub fn tool_definitions() -> Vec<Value> {+ let empty = || obj(json!({}), &[]);+ let app_only = |d: &str| format!("{d}{APP_ONLY}");+ vec![+ // ----- commands -----+ tool(+ "list_commands",+ "List commands",+ "List DesignCraft commands: id, label, menu path, shortcut, parameter description and whether it can run right now. \+ Every user-visible action is a command (frame.create, text.insert, type.char, style.paragraph.apply, layout.pages.insert, \+ object.fill, transform.move, edit.undo…); run them with execute or batch.",+ obj(+ json!({+ "filter": string("Case-insensitive substring matched against id, label and menu path (e.g. \"frame\", \"style\", \"Layout\")"),+ "enabledOnly": boolean("Only commands that can run right now"),+ }),+ &[],+ ),+ true,+ ),+ tool(+ "execute",+ "Execute command",+ "Run any DesignCraft command by id with JSON params (ids and params from list_commands). Examples: \+ {\"command\":\"frame.create\",\"params\":{\"rect\":[36,36,576,300],\"content\":\"text\",\"text\":\"Hello\"}} → {id, story}; \+ {\"command\":\"type.char\",\"params\":{\"size\":24}}; {\"command\":\"edit.undo\"}. Coordinates are points in spread space. \+ In the desktop app UI-only commands (view.*, window.*, app.*) work too.",+ obj(json!({"command": string("Command id, e.g. frame.create"), "params": params_schema()}), &["command"]),+ false,+ ),+ tool(+ "batch",+ "Execute commands",+ "Run several commands in order, stopping at the first error. Returns each result; on failure also the failing index \+ and message (earlier commands stay applied; use edit.undo to revert them).",+ obj(+ json!({"commands": {+ "type": "array",+ "minItems": 1,+ "description": "Commands to run in order",+ "items": obj(json!({"command": string("Command id"), "params": params_schema()}), &["command"]),+ }}),+ &["commands"],+ ),+ false,+ ),+ // ----- document -----+ tool(+ "inspect_document",+ "Inspect document",+ "Summary of the active document: settings, pages (index, name, bounds, margins, columns), spreads with items (id, kind, \+ bounds, fill, stroke, story), stories (id, frames, length, overset, preview), layers, paragraph/character styles, \+ swatches, selection, active tool.",+ empty(),+ true,+ ),+ tool(+ "get_story",+ "Get story",+ "Full text of a story plus its frames, paragraph count, line count and overset position. Identify it by `story` id or \+ by a text `frame` id (default: the selection).",+ obj(json!({"story": int("Story id"), "frame": int("Text frame id")}), &[]),+ true,+ ),+ tool(+ "set_story_text",+ "Set story text",+ "Replace the whole text of a story (keeps the first paragraph's and character's formatting). Use \\n for paragraph breaks. \+ Identify the story by `story` id or by a text `frame` id.",+ obj(json!({"story": int("Story id"), "frame": int("Text frame id"), "text": string("New text")}), &["text"]),+ false,+ ),+ tool(+ "new_document",+ "New document",+ "Create a new document and make it active. Sizes are in points (72 pt = 1 in). sample:true opens the multi-page \+ magazine sample instead.",+ obj(+ json!({+ "preset": string("Page size preset, e.g. \"Letter\", \"A4\", \"Tabloid\""),+ "width": num("Page width (pt)"),+ "height": num("Page height (pt)"),+ "pages": {"type": "integer", "minimum": 1, "description": "Number of pages"},+ "facingPages": boolean("Facing pages (spreads)"),+ "columns": {"type": "integer", "minimum": 1, "description": "Column count"},+ "gutter": num("Column gutter (pt)"),+ "margins": {"description": "Uniform margin (pt) or {top, bottom, inside, outside}", "anyOf": [{"type": "number"}, {"type": "object"}]},+ "bleed": num("Bleed on all sides (pt)"),+ "title": string("Document title"),+ "sample": boolean("Open the sample magazine instead"),+ }),+ &[],+ ),+ false,+ ),+ tool(+ "open_document",+ "Open document",+ "Open a .designcraft file as a new, active document.",+ obj(json!({"path": string("File path")}), &["path"]),+ false,+ ),+ tool(+ "save_document",+ "Save document",+ "Save the active document in the native .designcraft format.",+ obj(json!({"path": string("Destination (default: the document's current path)")}), &[]),+ false,+ ),+ tool(+ "place_image",+ "Place image",+ "Place an image (PNG, JPEG, WebP, GIF, TIFF) from a file `path` or `base64` data. It goes into `frame` (or the selected \+ empty/graphic frame), otherwise into a new frame at x, y (default: the page's top-left margin) with an optional width.",+ obj(+ json!({+ "path": string("Image file path"),+ "base64": string("Image bytes, base64 (alternative to path)"),+ "name": string("Name for base64 images"),+ "frame": int("Frame id to place into"),+ "spread": int("Spread index for a new frame (default 0)"),+ "x": num("Left of the new frame (spread pt)"),+ "y": num("Top of the new frame (spread pt)"),+ "width": num("Width of the new frame (pt); height follows the aspect ratio"),+ }),+ &[],+ ),+ false,+ ),+ // ----- looking -----+ tool(+ "render_page",+ "Render page",+ "Render one page of the active document (printing items only, like Preview) and return it as a PNG image. Optionally \+ also write it to `path`.",+ obj(+ json!({+ "page": int("Page index, 0-based (default 0; in the desktop app default = the current page)"),+ "scale": num("Pixels per point (default 1 = 72 ppi)"),+ "bleed": boolean("Include the bleed area"),+ "path": string("Also write the PNG here"),+ }),+ &[],+ ),+ true,+ ),+ tool(+ "export_png",+ "Export PNG",+ "Export one page as a PNG (or JPEG if the path ends in .jpg) file. Returns the path and pixel size.",+ obj(+ json!({"path": string("Destination file"), "page": int("Page index, 0-based (default 0)"), "scale": num("Pixels per point (default 2)")}),+ &["path"],+ ),+ false,+ ),+ tool(+ "screenshot",+ "Screenshot",+ &app_only("Capture the whole app window (menus, panels, canvas) and return it as a PNG image. Optionally also keep it at `path`."),+ obj(json!({"path": string("Also write the PNG here")}), &[]),+ true,+ ),+ // ----- input -----+ tool(+ "select_tool",+ "Select tool",+ "Switch the active tool (as clicking it in the Tools panel). Ids: selection, directSelection, type, rectangleFrame, \+ ellipseFrame, polygonFrame, rectangle, ellipse, polygon, line, hand, zoom, …",+ obj(json!({"tool": string("Tool id")}), &["tool"]),+ false,+ ),+ tool(+ "pointer",+ "Pointer gesture",+ "Drive the active tool with mouse events, exactly like the mouse would. Coordinates are spread points (space \"doc\", \+ default) or, in the desktop app, screen points (space \"screen\"). Example: a text frame with the type tool: \+ {tool:\"type\", events:[{kind:\"down\",x:72,y:72},{kind:\"drag\",x:300,y:200},{kind:\"up\",x:300,y:200}]} leaves a caret \+ in the new frame, ready for type_text. Returns the selection and the active tool.",+ obj(+ json!({+ "tool": string("Optional tool to select before the gesture"),+ "events": {+ "type": "array",+ "minItems": 1,+ "items": obj(json!({+ "kind": {"type": "string", "enum": ["down", "drag", "up", "move", "doubleclick"]},+ "x": num("x (pt)"),+ "y": num("y (pt)"),+ "space": {"type": "string", "enum": ["doc", "screen"], "description": "Coordinate space (default doc)"},+ "mods": mods_schema(),+ }), &["kind", "x", "y"]),+ },+ "mods": mods_schema(),+ }),+ &["events"],+ ),+ false,+ ),+ tool(+ "key",+ "Press key",+ "Press a key with modifiers, e.g. {key:\"Z\", cmd:true} (undo), {key:\"Escape\"}, {key:\"Enter\"}, {key:\"Left\", shift:true}. \+ In the desktop app it goes through the real keyboard path; headless it goes to the active tool (caret keys while typing), \+ then command shortcuts, then tool shortcuts.",+ obj(+ json!({+ "key": string("Key name: A–Z, 0–9, Enter, Escape, Delete, Backspace, Tab, Space, Left/Right/Up/Down, Home, End, [ ] …"),+ "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}, "ctrl": {"type": "boolean"},+ }),+ &["key"],+ ),+ false,+ ),+ tool(+ "type_text",+ "Type text",+ "Type text at the text insertion point (as the keyboard would with the type tool), or into the focused dialog field in \+ the desktop app. Put a caret first with pointer (tool \"type\") or execute text.placeCaret / text.select.",+ obj(json!({"text": string("Text to type (\\n = new paragraph)")}), &["text"]),+ false,+ ),+ tool(+ "click",+ "Click",+ &app_only(+ "Click at a screen point (egui points, top-left of the window = 0,0) through the real pointer path: reaches menus, \+ panels, flyouts and dialogs. Find coordinates with ui_inspect and screenshot.",+ ),+ obj(+ json!({+ "x": num("Screen x"), "y": num("Screen y"),+ "button": {"type": "string", "enum": ["left", "right"], "description": "Default left"},+ "count": {"type": "integer", "minimum": 1, "description": "2 = double-click"},+ "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}, "ctrl": {"type": "boolean"},+ }),+ &["x", "y"],+ ),+ false,+ ),+ tool(+ "drag",+ "Drag",+ &app_only("Press at (x, y), move to (toX, toY) in `steps` moves and release, in screen points through the real pointer path."),+ obj(+ json!({+ "x": num("Start x"), "y": num("Start y"), "toX": num("End x"), "toY": num("End y"),+ "steps": {"type": "integer", "minimum": 1, "description": "Intermediate moves (default 8)"},+ "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"},+ }),+ &["x", "y", "toX", "toY"],+ ),+ false,+ ),+ // ----- UI -----+ tool(+ "menu_list",+ "List menus",+ &app_only("The menu bar tree (menus, entries as cmd:/ui: command ids, separators, submenus)."),+ empty(),+ true,+ ),+ tool(+ "ui_inspect",+ "Inspect UI",+ &app_only("UI state: active tool, panels, view (zoom, origin), canvas rect in screen points, window size, documents, open dialog, perf."),+ empty(),+ true,+ ),+ tool(+ "ui_set",+ "Set UI state",+ &app_only(+ "Change UI state: panel to open, brightness, rulers/guides/frameEdges/baselineGrid/textThreads, screenMode, zoom, page (1-based), fit (page|spread).",+ ),+ obj(+ json!({+ "panel": string("Panel: properties, pages, layers, swatches, paragraphStyles, characterStyles, stroke, character, paragraph, textWrap, links"),+ "brightness": {"type": "string", "enum": ["dark", "mediumDark", "mediumLight", "light"]},+ "rulers": {"type": "boolean"}, "guides": {"type": "boolean"}, "frameEdges": {"type": "boolean"},+ "baselineGrid": {"type": "boolean"}, "textThreads": {"type": "boolean"},+ "screenMode": {"type": "string", "enum": ["normal", "preview", "bleed", "slug", "presentation"]},+ "zoom": num("1.0 = 100%"),+ "page": {"type": "integer", "minimum": 1, "description": "Go to page (1-based)"},+ "fit": {"type": "string", "enum": ["page", "spread"]},+ }),+ &[],+ ),+ false,+ ),+ tool(+ "dialog_set",+ "Set dialog field",+ &app_only("Set a field of the open dialog (see ui_inspect → dialog for its fields)."),+ obj(json!({"field": string("Field name"), "value": {"description": "New value"}}), &["field", "value"]),+ false,+ ),+ tool("dialog_confirm", "Confirm dialog", &app_only("Press OK in the open dialog."), empty(), false),+ tool("dialog_cancel", "Cancel dialog", &app_only("Press Cancel in the open dialog."), empty(), false),+ ]+}++// ---------- implementation ----------++type Args = Map<String, Value>;++fn req_str<'a>(a: &'a Args, k: &str) -> Result<&'a str, String> {+ a.get(k).and_then(Value::as_str).filter(|s| !s.is_empty()).ok_or_else(|| format!("missing string argument `{k}`"))+}++fn exec(b: &mut dyn Backend, cmd: &str, params: Value) -> Result<Value, String> {+ b.call("engine.execute", json!({"command": cmd, "params": params}))+}++fn need_ui(b: &dyn Backend, tool: &str) -> Result<(), String> {+ if b.has_ui() { Ok(()) } else { Err(format!("`{tool}` is not available headless; {NEEDS_APP}")) }+}++/// The given keys of `a` that are present, as a JSON object.+fn pick(a: &Args, 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 command_params(v: Option<&Value>) -> Result<Value, String> {+ match v {+ None | Some(Value::Null) => Ok(json!({})),+ Some(v @ Value::Object(_)) => Ok(v.clone()),+ Some(_) => Err("`params` must be an object".into()),+ }+}++fn filter_commands(all: Value, a: &Args) -> Value {+ let needle = a.get("filter").and_then(Value::as_str).map(str::to_lowercase).filter(|s| !s.is_empty());+ let enabled_only = a.get("enabledOnly").and_then(Value::as_bool).unwrap_or(false);+ let Value::Array(list) = all else { return all };+ let hit = |c: &Value| {+ if enabled_only && c.get("enabled").and_then(Value::as_bool) == Some(false) {+ return false;+ }+ let Some(n) = &needle else { return true };+ let field = |k: &str| c.get(k).and_then(Value::as_str).unwrap_or("").to_lowercase();+ let menu = c+ .get("menu")+ .and_then(Value::as_array)+ .map(|m| m.iter().filter_map(Value::as_str).collect::<Vec<_>>().join(" "))+ .unwrap_or_default()+ .to_lowercase();+ field("id").contains(n) || field("label").contains(n) || menu.contains(n)+ };+ Value::Array(list.into_iter().filter(hit).collect())+}++fn batch(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {+ let cmds = a.get("commands").and_then(Value::as_array).filter(|c| !c.is_empty()).ok_or("`commands` must be a non-empty array")?;+ let mut results = vec![];+ for (i, c) in cmds.iter().enumerate() {+ let step = (|| {+ let id = c.get("command").and_then(Value::as_str).filter(|s| !s.is_empty()).ok_or("missing `command`")?;+ exec(b, id, command_params(c.get("params"))?)+ })();+ match step {+ Ok(r) => results.push(r),+ Err(e) => {+ let v = json!({"completed": i, "results": results, "failedIndex": i, "failedCommand": c.get("command"), "error": e});+ return Ok(ToolResult { is_error: true, ..ToolResult::json(&v) });+ }+ }+ }+ Ok(ToolResult::json(&json!({"completed": results.len(), "results": results})))+}++/// The story id from `story` or the text frame `frame` (else the selection).+fn story_id(b: &mut dyn Backend, a: &Args) -> Result<Value, String> {+ if let Some(s) = a.get("story").filter(|v| v.is_u64()) {+ return Ok(s.clone());+ }+ let r = exec(b, "story.get", pick(a, &["frame"]))?;+ r.get("id").cloned().ok_or_else(|| "no story found (give `story` or a text `frame`)".into())+}++fn render_page(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {+ let r = b.call("ui.render", pick(a, &["page", "scale", "bleed"]))?;+ let b64 = r.get("pngBase64").and_then(Value::as_str).ok_or("renderer returned no image")?.to_string();+ let path = a.get("path").and_then(Value::as_str);+ if let Some(path) = path {+ let png = designcraft_engine::cmd::base64_decode(&b64);+ std::fs::write(path, png).map_err(|e| format!("write {path}: {e}"))?;+ }+ Ok(ToolResult::image(b64, &json!({"width": r.get("width"), "height": r.get("height"), "path": path})))+}++fn screenshot(b: &mut dyn Backend, a: &Args) -> Result<ToolResult, String> {+ need_ui(b, "screenshot")?;+ // The app writes the capture to disk (loopback: same machine), then we read it back.+ let keep = a.get("path").and_then(Value::as_str);+ let target = match keep {+ Some(p) => p.to_string(),+ None => std::env::temp_dir()+ .join(format!("designcraft-mcp-{}-{}.png", std::process::id(), std::time::SystemTime::UNIX_EPOCH.elapsed().map_or(0, |d| d.as_millis())))+ .to_string_lossy()+ .to_string(),+ };+ let r = b.call("ui.screenshot", json!({"path": target}))?;+ let png = std::fs::read(&target).map_err(|e| format!("read {target}: {e}"))?;+ if keep.is_none() {+ std::fs::remove_file(&target).ok();+ }+ Ok(ToolResult::image(designcraft_engine::cmd::base64_encode(&png), &json!({"width": r.get("width"), "height": r.get("height"), "path": keep})))+}++fn pointer(b: &mut dyn Backend, a: &Args) -> Result<Value, String> {+ let events = a.get("events").and_then(Value::as_array).filter(|e| !e.is_empty()).ok_or("`events` must be a non-empty array")?;+ for (i, e) in events.iter().enumerate() {+ let kind = e.get("kind").and_then(Value::as_str).unwrap_or("");+ if crate::headless::pointer_kind(kind).is_none() {+ return Err(format!("event {i}: unknown kind `{kind}` (down, drag, up, move, doubleclick)"));+ }+ if !e.get("x").is_some_and(Value::is_number) || !e.get("y").is_some_and(Value::is_number) {+ return Err(format!("event {i}: numeric `x` and `y` required"));+ }+ }+ if let Some(t) = a.get("tool").and_then(Value::as_str) {+ b.call("ui.tool.select", json!({"tool": t}))?;+ }+ b.call("ui.pointer", pick(a, &["events", "mods"]))+}++fn dispatch(b: &mut dyn Backend, name: &str, a: &Args) -> Result<ToolResult, String> {+ let j = |v: Value| Ok(ToolResult::json(&v));+ match name {+ "list_commands" => {+ let all = b.call("engine.commands", json!({}))?;+ let list = filter_commands(all, a);+ j(json!({"count": list.as_array().map_or(0, Vec::len), "commands": list}))+ }+ "execute" => {+ let cmd = req_str(a, "command")?;+ let params = command_params(a.get("params"))?;+ j(exec(b, cmd, params)?)+ }+ "batch" => batch(b, a),+ "inspect_document" => j(b.call("document.inspect", json!({}))?),+ "get_story" => j(exec(b, "story.get", pick(a, &["story", "frame"]))?),+ "set_story_text" => {+ let text = a.get("text").and_then(Value::as_str).ok_or("missing string argument `text`")?.to_string();+ let sid = story_id(b, a)?;+ exec(b, "story.setText", json!({"story": sid, "text": text}))?;+ j(exec(b, "story.get", json!({"story": sid}))?)+ }+ "new_document" => {+ if a.get("sample").and_then(Value::as_bool) == Some(true) {+ return j(exec(b, "file.newSample", json!({}))?);+ }+ let mut p = a.clone();+ p.remove("sample");+ j(exec(b, "file.new", Value::Object(p))?)+ }+ "open_document" => j(b.call("app.open", json!({"path": req_str(a, "path")?}))?),+ "save_document" => j(exec(b, "file.save", pick(a, &["path"]))?),+ "place_image" => {+ if !a.contains_key("path") && !a.contains_key("base64") {+ return Err("give `path` or `base64`".into());+ }+ j(exec(b, "file.place", pick(a, &["path", "base64", "name", "frame", "spread", "x", "y", "width"]))?)+ }+ "render_page" => render_page(b, a),+ "export_png" => {+ req_str(a, "path")?;+ j(b.call("app.export", pick(a, &["path", "page", "scale"]))?)+ }+ "screenshot" => screenshot(b, a),+ "select_tool" => j(b.call("ui.tool.select", json!({"tool": req_str(a, "tool")?}))?),+ "pointer" => j(pointer(b, a)?),+ "key" => {+ req_str(a, "key")?;+ j(b.call("ui.key", pick(a, &["key", "shift", "alt", "cmd", "ctrl"]))?)+ }+ "type_text" => j(b.call("ui.text", json!({"text": req_str(a, "text")?}))?),+ "click" | "drag" => {+ need_ui(b, name)?;+ let keys: &[&str] = &["x", "y", "toX", "toY", "steps", "button", "count", "shift", "alt", "cmd", "ctrl"];+ j(b.call(if name == "click" { "ui.click" } else { "ui.drag" }, pick(a, keys))?)+ }+ "menu_list" => {+ need_ui(b, name)?;+ j(b.call("ui.menu.list", json!({}))?)+ }+ "ui_inspect" => {+ need_ui(b, name)?;+ j(b.call("ui.inspect", json!({}))?)+ }+ "ui_set" => {+ need_ui(b, name)?;+ j(b.call("ui.set", Value::Object(a.clone()))?)+ }+ "dialog_set" => {+ need_ui(b, name)?;+ j(b.call("ui.dialog.set", json!({"field": req_str(a, "field")?, "value": a.get("value")}))?)+ }+ "dialog_confirm" => {+ need_ui(b, name)?;+ j(b.call("ui.dialog.confirm", json!({}))?)+ }+ "dialog_cancel" => {+ need_ui(b, name)?;+ j(b.call("ui.dialog.cancel", json!({}))?)+ }+ other => Err(format!("unknown tool `{other}` (see tools/list)")),+ }+}++/// Run one tool. Failures (unknown tool, bad arguments, command errors) come back as an+/// `isError` result so the model can read and correct them.+pub fn call_tool(b: &mut dyn Backend, name: &str, args: &Value) -> ToolResult {+ let empty = Map::new();+ let a = match args {+ Value::Object(o) => o,+ Value::Null => &empty,+ _ => return ToolResult::error("tool arguments must be a JSON object"),+ };+ match dispatch(b, name, a) {+ Ok(r) => r,+ Err(e) => ToolResult::error(format!("{name}: {e}")),+ }+}diff --git a/docs/mcp.md b/docs/mcp.mdnew file mode 100644index 000000000..4ed2a3e87--- /dev/null+++ b/docs/mcp.md@@ -0,0 +1,92 @@+# MCP server++`designcraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude and+other agents drive DesignCraft: create documents, lay out frames and text, apply styles, place images, and look at+the result as PNG images. It speaks newline-delimited JSON-RPC 2.0 on stdin/stdout (protocol `2025-06-18`, also+`2025-03-26` and `2024-11-05`); logs go to stderr. The implementation is the `designcraft-mcp` crate.++## Register it++Build the CLI (`cargo build --release -p designcraft-cli`), then:++```sh+# Headless: an in-process engine, no window+claude mcp add designcraft -- /path/to/target/release/designcraft-cli mcp++# Drive the running desktop app (start it first with a control port)+designcraft --control 7979+claude mcp add designcraft-app -- /path/to/target/release/designcraft-cli mcp --connect 7979+```++Other MCP clients use the same command line, e.g. in a JSON config:++```json+{"mcpServers": {"designcraft": {"command": "/path/to/designcraft-cli", "args": ["mcp"]}}}+```++## Modes++| | Headless (`mcp`) | Connected (`mcp --connect PORT` or `HOST:PORT`) |+|---|---|---|+| Engine | In-process `designcraft_engine::Session`, starts with an empty Letter document (`--sample` opens the sample magazine) | The app's session, through its loopback control channel ([control-protocol.md](control-protocol.md)) |+| Rendering | `designcraft-render` (CPU) | The app's renderer |+| Window tools (`screenshot`, `click`, `drag`, `menu_list`, `ui_inspect`, `ui_set`, `dialog_*`) | Return an error explaining how to connect | Work |+| UI-only commands (`view.*`, `window.*`, `app.*`) via `execute` | Error | Work |++In connected mode every tool maps to a control-channel method (`engine.execute`, `ui.render`, `ui.pointer`, …), so+what the agent does shows up live in the window. The connection is re-established once if the app restarts.++## Coordinates++Points (1/72 in), y down, in **spread** space: on a single-page spread the page's top-left is (0, 0); on a facing+spread the right page starts at x = page width. `inspect_document` lists page bounds per spread. Page indices in+`render_page` / `export_png` are 0-based. `pointer` events in connected mode may use `"space": "screen"` (egui points,+see `ui_inspect` → `canvasRect`).++## Tools++| Tool | What it does |+|---|---|+| `list_commands` | Every command (id, label, menu path, shortcut, params, enabled), with `filter` / `enabledOnly` |+| `execute` | Run any command: `{command, params}` |+| `batch` | Run `commands: [{command, params}]` in order, stopping at the first error (reports `failedIndex`) |+| `inspect_document` | Pages, spreads, items (ids, bounds, fill, story), stories (overset), layers, styles, swatches, selection |+| `get_story` | Text, frames, paragraphs, lines, overset of a story (`story` or text `frame`) |+| `set_story_text` | Replace a story's text (`\n` = new paragraph) |+| `new_document` | `file.new` (preset, width, height, pages, facingPages, columns, gutter, margins, bleed, title) or `sample: true` |+| `open_document` / `save_document` | Native `.designcraft` files |+| `place_image` | Image from `path` or `base64` into `frame`, the selected frame, or a new frame at x, y, width |+| `render_page` | Render a page → MCP image content (PNG, base64); optional `path` to also save it |+| `export_png` | Write a page as PNG (or JPEG by extension) |+| `screenshot` | Whole app window → image content (connected only; captured to a temp file and read back) |+| `select_tool` | Activate a tool (`selection`, `type`, `rectangleFrame`, `line`, …) |+| `pointer` | Mouse gesture events (`down`/`drag`/`up`/`move`/`doubleclick`) for the active tool, optional `tool` |+| `key` | Key press with modifiers (headless: active tool → command shortcuts → tool shortcuts) |+| `type_text` | Type at the text insertion point (or into the focused dialog field in the app) |+| `click` / `drag` | Real pointer input at screen points (connected only) |+| `menu_list`, `ui_inspect`, `ui_set` | Menu tree, UI state, change UI state (connected only) |+| `dialog_set` / `dialog_confirm` / `dialog_cancel` | Fill in and close the open dialog (connected only) |++Tool failures come back as results with `isError: true` and a message the model can act on; protocol errors use+JSON-RPC error codes. Resources: `designcraft://document` (document.inspect) and `designcraft://commands`.++## Example++```text+new_document {"preset": "A4", "margins": 36}+execute {"command": "frame.create", "params": {"rect": [36, 36, 559, 200], "content": "text", "text": "Hello"}}+ → {"id": 8, "story": 9}+set_story_text {"story": 9, "text": "Summer Fair\nSaturday in the park"}+execute {"command": "type.char", "params": {"size": 28}}+place_image {"path": "/tmp/photo.jpg", "x": 36, "y": 220, "width": 523}+render_page {"page": 0} → PNG image+```++Or with the Type tool, the way a user would:++```text+pointer {"tool": "type", "events": [{"kind": "down", "x": 72, "y": 72}, {"kind": "drag", "x": 300, "y": 200}, {"kind": "up", "x": 300, "y": 200}]}+type_text {"text": "Hello"}+key {"key": "Enter"}+key {"key": "Escape"}+```