# Letting an agent edit a Manifold document

Manifold documents are `.mfld` files, and this is a small [MCP](https://modelcontextprotocol.io)
server that lets an agent — Claude Code, AntiGravity, anything that speaks MCP —
read and edit one.

## Pointing an agent at it

It runs over stdio, so the agent starts it. There is no port, nothing listening,
and nothing to turn on:

```json
{
  "mcpServers": {
    "manifold": {
      "command": "node",
      "args": ["/path/to/Manifold/mcp/server.mjs"]
    }
  }
}
```

Then ask for what you want in words — *"open ~/papers/thesis.mfld and tighten the
introduction"*. The tools are described well enough that nothing has to be
explained to the model first.

## What it can do

| | |
|---|---|
| `document_info` | the heading outline, the counts, the class and paper — **read this first**, its block numbers are the addresses everything else uses |
| `read_blocks` | the blocks in order, with their text and the LaTeX of any formulas |
| `search` | find text, and the block it is in |
| `set_block_text` | replace one block's words, keeping what it is |
| `set_block_style` | change what a block *is* — Section, Quote, Theorem, Proof… |
| `insert_block` | add a paragraph or heading |
| `delete_block` | remove one |

## Three things it will not do

**It will not write a document Manifold has open.** Manifold's autosave rewrites
the file you chose, so an edit made from outside would be erased by the app's
next save — silently, with no version kept, because the app never saw it happen.
The server refuses and says which document to close. Reading is always allowed.

**It will not write a file Manifold could not open.** Every edit is parsed
through the app's own schema before it reaches the disk, and the file is written
beside and renamed, so a crash during the write cannot leave half a document
where a whole one was.

**It will not hand a model the raw file.** A model given the JSON tree will
produce documents that do not parse; given `set_block_text` it cannot. The tools
are the vocabulary, and the schema is the guard behind them.

## Keeping it honest

`mcp/lib/schema.mjs` is the app's own reader, bundled for Node
(`npm run build:mcp`). One copy, because two drift — and drift here means a file
this writes that Manifold will not open. `tests/mcp-bundled.mjs` fails when it is
older than its sources; `tests/mcp.mjs` drives the server the way an agent does.
