Skip to content

The MCP server ​

From the spec

This page is spec/mcp.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).

weft mcp gives an outside agent the APIs the editor uses (docs/editor.md, The agent and the MCP server). It is a Model Context Protocol server on stdio, in weft-cli's src/mcp/, built on the rmcp SDK. The agent can read a project, ask the analysis, edit through the edit API (with undo and rename), see a page or component as a screenshot with its element map, and run the tests. When a weft dev serves the project, the server attaches to it, so each edit swaps into the running app.

sh
claude mcp add weft -- weft mcp          # Claude Code, in the project's folder
weft mcp [project]                       # any MCP client: the project is the folder's (default: the current one)

The project is the nearest folder holding weft.toml above the path, as for every command. The server's stdout carries only the protocol. Anything the compiler, the runtime or a child process prints goes to stderr: the server keeps a private copy of stdout and points stdout itself at stderr.

Modes ​

  • files (the default): the server holds the project in a weft-edit workspace (the files, their node ids, the revisions, this client's undo) and a weft-analysis analysis. An applied edit is written to the files.
  • dev: a weft dev serves the project. Its .weft/dev.json names it, and its pid is alive. The server connects to its editor protocol (spec/editor-protocol.md) with a ticket bought with the dev token. Edits then go through the protocol's apply: weft dev writes the files, maps the ids and swaps the new build into its pages. Node ids are the dev session's, which are the ids the pages' locations carry.

Before each call the server takes in what changed on disk, mapping ids through the change (Workspace::replace_text). It also attaches to a weft dev that has started, or lets go of one that stopped. Switching modes starts a fresh undo history. The result of the call that switched says so in notes.

Rendering a route needs a server. When none is attached, render starts a weft dev of its own on a free port on 127.0.0.1 and attaches to it. The server stops that weft dev, and the app server under it, when it exits. A weft dev started by someone else is never stopped.

The tools ​

Every tool takes one JSON object, described by its JSON Schema (tools/list), and returns one JSON value. The value comes as the result's text and as its structuredContent; screenshots are added as image content. Files are named by id: the path from the root without .weft (routes/page, components/TodoRow). A place in a file is node (an id from outline; it points at the node's first name), line and column (1-based, in characters), or offset (bytes).

toolwhat it does
projectfiles with their kinds (page, layout, component, module), routes, weft.toml (its text), the mode (and the weft dev's URL), error and warning counts
read_filea file's source, or lines from..to
outlinea file's addressable nodes as a tree: id, kind, tag, line, column, depth, a line of text (expressions only with expressions); its top-level symbols
schemathe primitives and their props' names; with primitive, its props in full, its look and the schema's attributes
themethe theme's tokens (colours, fonts, lengths, shadows, schemes) and the style scales, from the schema and theme.weft; query lists matching class tokens
docsthe embedded spec/ and site/guide/: the list, a doc by path (or one section), or the lines matching a query
apieach module's exported declarations (each component's too) with signatures, and the API the app exports to user code (weft api --json, when its runs of user code import any)
diagnosticserrors (and warnings with warnings) per file, each with its fix-its as ops ready for edit
hoverthe analysis's hover at a place
referencesthe definition and every reference of the name at a place
completionsthe analysis's completions at a place, best first (limit, default 40)
editapplies a batch atomically (below); the new source of each changed file, the diagnostics, the errors it introduced
undo, redothis client's last batch taken back or applied again, as one step
renamea declaration and every reference renamed across the project, as one undoable step
rendera route or a component as a PNG screenshot, with the element map, optionally the HTML (below)
runtimea dev-runtime call on the page render opened, optionally followed by a screenshot
testweft test (all, name, or files; list): each test's status, file, line and failure
checkweft check --json over the project or files (target)
conformancein the markup-kit repo: the corpus cases under conformance/lang/<path>, on the VM (part: vm) or through weft check (part: check)

Errors are values. A failed call returns { "error": { "code", "message", "fix" } } and is marked isError. fix says what to do next: the files near a misspelt id, "call outline for the current node ids", "include more of the surrounding text so it occurs once". A rejected edit adds the diagnostics behind it. Unknown tools and malformed calls are errors too; protocol errors are kept for requests the server can't route.

Edits ​

edit takes { file?, ops, on_error?, source? }. Its ops are the edit API's operations (spec/edit.md, Operations, each with its schema), applied at the Code level, plus two of the server's own:

  • { "op": "replace", "file", "old", "new" }: exact text that must occur once in the file. It becomes a patch, read against the text as the batch's earlier replaces leave it. A replace after a structured op on the same file is refused: send it in a batch of its own.
  • { "op": "patch", "file", "range": [start, end], "text" }: a patch of one edit, as the editor protocol writes it.

An applied batch answers { status: "applied", revision, files: [{ file, source, created, removed }], introduced, errors, diagnostics }; source: false leaves the sources out. The diagnostics, and the count of errors the batch introduced, come from the analysis, so both modes answer alike. In dev mode the answer also has live, and on_error: refuse isn't available, since weft dev applies every batch. rename with a node is the edit API's rename op. With a place, it renames the innermost addressable node whose first name is there; otherwise it applies the analysis's per-file edits as one batch of patches.

Render ​

render takes { path, width?, height?, scheme?, full_page?, screenshot?, html?, elements?, reload?, props?, env? }. The viewport defaults to 1024 × 768 at device pixel ratio 1.

  • A route (path starts with /) is the app's real page on weft dev, opened in headless Chromium. Chromium is driven over the DevTools protocol, and one browser and one page are kept between calls. The page runs the dev build: hot swaps from later edits land in it and its state stays, unless reload. The element map comes from the page's dev runtime (map, spec/editor-protocol.md). A page that ships no JS has no dev runtime, so its map is empty, with a note.
  • A component (path a file id, with props as JSON values and env) is rendered in this process. It is checked, compiled as a dev build with the session's node ids, mounted on a server runtime, and written as HTML with each drawn element marked data-weft-node="file#id" (Runtime::html_located). The project's CSS goes inline in the page Chromium opens.
  • The element map lists every drawn element with a box: { node: "routes/page#12", tag, text, box: [x, y, width, height], instance }, in CSS pixels, in document order, at most 400. node is the id outline and edit use, so the agent can point at what it sees and edit it.
  • The screenshot is returned as an image and saved as .weft/mcp/shots/<n>-<path>.png; the result gives the path. Chromium is $WEFT_CHROMIUM, or chromium, chromium-browser or google-chrome on PATH. Without one, the result is the no_browser error, and screenshot: false still gives the HTML and the map of a component.

runtime takes { method, args?, screenshot? }: elementAt, rendered, instances, blocks, forceBranch, setState, clearPreviews, map and text. It calls the dev runtime of the page render opened, through the page's __weftDev, so preview states land in the page the screenshots come from. Preview states never edit code.

Run ​

test and check run this weft binary as a child, in the project's folder, with a timeout, and parse what it prints. conformance runs cargo test -j2 -p weft-runtime --test corpus (or -p weft-cli --test conformance) in the repo's core/ with CASE=<path>, and reads CORPUS_REPORT for the failures.

Resources ​

Memory on a shared host is the caller's to cap: everything the server starts (weft dev, the app's server, Chromium, cargo) runs in its process group or cgroup. On the NAS run the client capped, for example systemd-run --user --scope -q -p MemoryMax=3G -p MemorySwapMax=0 claude …, so its whole tree stays inside the cap.

Tests ​

  • cargo test -p weft-cli --test mcp drives the binary over a copy of tests/mcp-app:
    • initialize and list the tools;
    • read the project, an outline, the schema, the theme, the docs and the API;
    • edit with diagnostics, an edit that introduces an error, undo (ids kept), and rejections with their fixes;
    • hover, references and completions;
    • rename across files, a prop given as a shorthand on its tag, undo and redo;
    • render a component (its HTML and element map), then test and check;
    • render /, which starts a weft dev and attaches to it: a PNG, the element map and runtime when Chromium is there, else the no_browser error;
    • an edit through weft dev that reaches the page by hot swap, then undo;
    • stdin closed: the server and the weft dev it started stop.
  • The repo's check runs it with Chromium (WEFT_CHROMIUM, Playwright's from the cache: docs/ci.md); in a sandbox, WEFT_CHROMIUM=$(sh scripts/ci-chromium.sh). The client build (pnpm build:client) gives pages their dev runtime.

Decided here ​

  1. The worker owns the state. rmcp's handler only queues each call for one worker thread. That thread owns the workspace, the analysis (which isn't Send), the protocol connection and the child processes, and stops them when the client goes.
  2. Attach, don't compete. With a weft dev running, edits go through its protocol and ids are its session's, so the map from a screenshot names the same nodes outline and edit do. The server never writes the files behind weft dev's back.
  3. The real page for routes. A route renders on weft dev in Chromium rather than by server rendering in process, so apps whose startup needs the server host (std/http, std/auth, std/db) render as they serve. Components render in process.
  4. Exact text before byte offsets. replace is the server's own source patch, because agents quote text more reliably than they count bytes. Structured ops stay the way to edit by node.

Not yet ​

  • Input on the page (click, type, scroll) beyond the dev runtime's preview states.
  • The desktop renderer's screenshots (weft-desktop shot) beside Chromium's.
  • Several clients sharing one server's undo history; resources and prompts.

Weft is in development. The reference is the spec as it stands today.