Graft

What Graft does

The Graft MCP server places a read-policy layer between a coding agent and a repository filesystem. Rather than returning every requested file in full, it selects the smallest structurally valid representation available:

• Small files can be returned as complete content.
• Large source files can be represented by parser-backed outlines containing symbols, signatures, hierarchies, and line ranges.
• Secrets, binaries, and lockfiles can be refused with a machine-readable reason and an alternative action.

This approach is intended for the 🤖 Coding Agents category, where context usage affects how effectively an agent can inspect and modify a codebase. An agent can request a narrower range after reviewing an outline instead of loading an entire large module.

Responses include versioned schema metadata and decision receipts. Receipts report values such as bytes consumed, bytes avoided, session depth, policy decisions, and cumulative session statistics. These records let agents and operators inspect how much context a session is using.

How it works

Graft exposes three entry points: a command-line interface, MCP sessions, and an in-process API. The MCP runtime communicates through JSON-RPC on stdin and stdout. Repo-local stdio uses the current checkout directly. Daemon-backed stdio supports persistent same-user operation, multiple repositories, worktrees, actor lanes, and monitors that keep structural history current.

The Graft MCP server can use WARP, its structural history layer, to query changes such as added, removed, or renamed symbols without placing complete source files in the context window. Its session tracker also watches for patterns including repeated tool loops, late-session large reads, and edit or shell-command thrashing; tripwire signals appear in receipts.

For daemon sessions, a repository tool can receive an explicit cwd to route a call to a worktree. workspace_open, workspace_authorize, and workspace_bind provide progressively more direct workspace control. Private WARP sidecar data is kept outside the source repository by default, under ~/.graft/graphs, or under the directory selected by GRAFT_ROOT_PATH.

Setup and configuration

Install and bootstrap a repository with the package’s npx command:

npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
npx @flyingrobots/graft serve

The initialization command creates or updates .graftignore, adds agent read guidance, and writes client configuration according to the flags supplied. A governed command-line read can be tested with:

npx @flyingrobots/graft read safe src/app.ts

Use npx @flyingrobots/graft serve for a repo-local MCP process. For persistent multi-repository work, start npx @flyingrobots/graft daemon and connect with serve --runtime daemon. The executable can also detect non-interactive stdio and enter serve mode without an explicit subcommand.

Tools and capabilities

The documented MCP capabilities include:

• safe_read for policy-governed file access.
• file_outline for structural views of files.
• read_range for focused source retrieval after an outline.
• changed_since, graft_diff, graft_since, and graft_map for structural change and history queries.
• code_show, code_find, and code_refs for syntax-oriented code inspection.
• workspace_list_opened, workspace_open, workspace_authorize, and workspace_bind for daemon workspace management.

Tree-Sitter supplies parser-backed outlines for languages and formats including JavaScript, TypeScript, Rust, Python, Go, GraphQL, JSON, TOML, YAML, and Markdown. The API can also expose governed reads, in-process tool calls with receipts, and editor-oriented Tree-Sitter WASM syntax data without starting a subprocess.

Limitations and notes

Graft does not promise full file content for every request. Large files may produce outlines, and protected file classes may produce refusals. Agents must use the Graft read tools rather than bypassing the policy with direct filesystem reads if governed behavior is required.

Repo-local MCP is intended for a single checkout, while daemon-backed sessions add workspace routing and persistent sidecar state. WARP graph stores are separated by project, worktree, and actor. Advanced graph-root overrides fail closed when they are blank, symlink-aliased, or overlap the source worktree or common Git directory.

The in-process API is available when an application needs Graft behavior without MCP transport or a child process. Its governed repository-read example does not include receipts, while direct in-process tool calls provide full MCP behavior with receipts.