aleleba/vectorcraft
1
0
Fork 0
mirror of https://github.com/storytold/vectorcraft.git synced 2026-10-28 03:37:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #713 from storybored379/feat/mcp-conventions

Browse Source 
MCP: common command tools, strict arguments and session resources
This commit is contained in:
BFlat
2026-10-09 14:56:41 +07:00
committed by GitHub
parent e4a7c64ccb 829ec48581
commit 24c77e9ddf
10 changed files with 355 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mcp.md
+37 -8
View File
@@ -1,7 +1,7 @@
# VectorCraft MCP server
`vectorcraft-cli mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio
(newline-delimited JSON-RPC 2.0, protocol `2025-06-18`; `2025-03-26` and `2024-11-05` also accepted). Agents use it to
(newline-delimited JSON-RPC 2.0; see [Protocol](#protocol) for version negotiation). Agents use it to
draw, inspect and look at VectorCraft documents.
It has two backends:
@@ -35,16 +35,18 @@ For a live session, start the app first: `cargo run --release -p vectorcraft --
## Protocol
Newline-delimited JSON-RPC 2.0 on stdio. The revision is **`2025-06-18`**; `2025-03-26` and `2024-11-05` are
accepted too, and `initialize` answers with whichever of those the client asked for. The specs' own
`resultType` fields and the `2026-07-28` revision are not implemented — see
[Not implemented](#not-implemented).
accepted too. Clients requesting `2026-07-28` through `initialize`, or through a request's
`_meta["io.modelcontextprotocol/protocolVersion"]`, receive `resultType: "complete"`,
`ttlMs` and `cacheScope: "private"` on tool/resource/template/prompt lists and resource/prompt reads.
List TTL is 600000 ms; live reads use zero. Older clients keep the original response shapes.
This does not add streaming or input requests — see [Not implemented](#not-implemented).
`initialize` advertises:
| Capability | What it covers |
|---|---|
| `tools` | The 25 tools below |
| `resources` | Two fixed documents and four templates |
| `tools` | The tools below |
| `resources` | Three fixed resources and four templates |
| `prompts` | Five ready-made workflows |
| `completions` | `completion/complete` for prompt arguments and template variables |
| `logging` | `logging/setLevel` and `notifications/message` |
@@ -69,8 +71,8 @@ echo '{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"poster","
### Resource templates
`vectorcraft://document` (summary) and `vectorcraft://document/json` (the whole model) are the fixed
resources. The templates read one thing at a time, which matters on a real document: the full model
`vectorcraft://document` (summary), `vectorcraft://document/json` (the whole model), and
`vectorcraft://commands` (the live command catalog with enabled state) are the fixed resources. The templates read one thing at a time, which matters on a real document: the full model
is thousands of lines an agent pays for again on every change.
| `uriTemplate` | Reads |
@@ -123,6 +125,12 @@ crate that installed one would override whatever logger an embedder had already
`vectorcraft-mcp` directly means calling `vectorcraft_mcp::logging::install()` yourself if you want
log records to reach your client.
### Synchronous calls
Exports complete synchronously. A `_meta.progressToken` is harmlessly ignored, as are
`notifications/cancelled` (including unknown request ids). There are no background export jobs
or progress notifications; cancellation cannot interrupt a running call.
### Not implemented
Everything below needs the same thing first: the server reads one line at a time and answers it with
@@ -150,6 +158,27 @@ the transport — a design change rather than a feature, so it is not in this cr
## Tools
### Common command tools
These names match the conventions in [FilmCraft #28](https://github.com/storytold/filmcraft/pull/28).
The older names below remain listed because existing workflows use them.
| Tool | Arguments and result |
|---|---|
| `command_list` | Optional `filter`, `enabled_only`; returns the command array |
| `command_run` | `id`, optional `params`; runs the command through the existing backend |
| `command_batch` | `steps: [{id, params?}]`, optional `stop_on_error` (default true); returns `completed`, `failed`, `results: [{ok, result\|error}]`. Each edit has its own undo step; failures set `isError` |
| `doc_inspect` | Optional `depth`, `childLimit`; same summary as `inspect_document` |
| `render_preview` | Optional `max_side` (1–4096, default 1024); inline PNG of the first artboard without editing it. Artboards too large to render within the allocation bound return a tool error |
| `ui_inspect`, `ui_screenshot` | Connected desktop state/window capture; tool errors in headless mode |
Every tool declares read-only, destructive, idempotent and open-world hints. File-writing
`screenshot`, `save_file` and `export` are conservatively marked as mutations. Unknown top-level
argument keys return JSON-RPC `-32602`; command failures and caught tool panics return `isError`
content, and the server continues serving. Command `params` are passed through: the registry
currently describes them in prose, so MCP does not guess schemas or silently remove keys.
Coordinates are points in document space: y points down, the origin is the first artboard's top-left, and a new
document is 612 × 792 (US Letter). New objects become the selection. Most commands act on the selection or on
explicit `ids`.