# Graft [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/flyingrobots/graft  
**GitHub Stars:** 17  
**npm Downloads (last month):** 571  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/flyingrobots-graft

## Description
Context governor and between-commit activity surface for coding agents

## Tools
Capabilities this server exposes over MCP:

- **safe_read** — Policy-enforced file read. Returns full content for small files, structural outline with jump table for large files, or refusal with reason code for banned files. Detects re-reads and returns cached outlines or structural diffs.
- **graft_edit** — Perform one governed exact string replacement in a repo file. Requires path, old_string, and new_string. Refuses missing or ambiguous old_string matches and policy-denied paths.
- **file_outline** — Structural skeleton of a file — function signatures, class shapes, exports. Includes a jump table mapping each symbol to its line range for targeted read_range follow-ups.
- **read_range** — Read a bounded range of lines from a file. Maximum 250 lines. Use jump table entries from file_outline or safe_read to target specific symbols.
- **changed_since** — Check if a file changed since it was last read. Returns structural diff (added/removed/changed symbols) or 'unchanged'. Peek mode by default; pass consume: true to update the observation cache.
- **graft_diff** — Structural diff between two git refs. Shows added, removed, and changed symbols per file — not line hunks. Defaults to working tree vs HEAD.
- **run_capture** — Execute a shell command and return the last N lines of output (default 60). Responses include an explicit policy boundary. Persisted logs can be disabled and obvious secrets are redacted before writing to .graft/logs/capture.log.
- **state_save** — Save session working state (max 8 KB). Use for session bookmarks: current task, files modified, next planned actions.
- **state_load** — Load previously saved session state. Returns null if no state has been saved.
- **doctor** — Runtime health check. Shows project root, parser status, active thresholds, session depth, message count, and burden summary.
- **activity_view** — Inspect recent bounded local artifact history for the active workspace, anchored to the current commit when possible.
- **causal_status** — Inspect the active causal workspace and persisted local-history posture.
- **causal_attach** — Explicitly declare lawful continuation or handoff for the current causal workspace.
- **workspace_open** — Open a git worktree path in this MCP session and optionally make it the active workspace.
- **workspace_list_opened** — List workspaces opened in this MCP session and identify the active workspace.
- **workspace_status** — Return the current daemon workspace binding state and resolved capability profile.
- **stats** — Decision metrics for the current session. Total reads, outlines, refusals, cache hits, bytes avoided, and burden by tool kind.
- **explain** — Explain a graft reason code. Returns human-readable meaning and recommended next action for any reason code returned by graft tools.
- **set_budget** — Declare a context byte budget for this session. Graft tightens read thresholds as the budget drains — no single read may consume more than 5% of remaining budget. Call once at session start.
- **graft_since** — Structural changes since a git ref. Shows symbols added, removed, and changed per file — not line hunks. Includes per-file summary lines for quick triage. Defaults to HEAD as the comparison target.
- **graft_map** — Structural map of a directory — all files and their symbols (function signatures, class shapes, exports) in one call. Uses tree-sitter to parse the working tree directly.
- **code_show** — Focus on a symbol by name and return its source code in one call. Provide a path to target a specific file, or omit to search the project. Returns source, signature, and location.
- **code_find** — Search for symbols across the project by approximate name or glob pattern. Returns matches with file path, kind, signature, and line range. Use code_show to read the source of a specific match.
- **code_refs** — Search for import sites, callsites, property access, or literal text references across the working tree. Returns explicit text-fallback matches with the engine, pattern, and scope used.
- **graft_churn** — Structural churn report — which symbols change most frequently? Identifies maintenance hotspots by walking indexed commits and counting per-symbol change frequency.
- **graft_exports** — Export surface diff — what changed in the public API between two refs? Identifies added, removed, and signature-changed exported symbols and derives semver impact.
- **graft_log** — Structural git log — shows symbol-level changes (added, removed, changed) per commit. Like `git log` but for code structure, not lines.
- **graft_blame** — Symbol-level blame: who last changed a symbol's signature, when it was created, and its full change history. Returns creation commit, last signature change, change count, reference count, and chronological history.
- **graft_difficulty** — Refactor difficulty score for a symbol. Combines WARP aggregate churn curvature with WARP reference-edge friction so agents can choose refactor vs workaround.
- **graft_review** — Zero-noise structural PR review. Categorizes changed files as structural, formatting, test, docs, or config. Detects breaking changes (removed exports, changed signatures) with impact counts.
- **graft_import_diagnostics** — Report first-party import bindings whose lexical shadows exclude qualified reference inference.
- **graft_test_coverage** — Structural/reference test coverage map. Reports exported source symbols with or without obvious references in the configured test directory, without claiming execution coverage.
- **graft_dead_symbols** — Dead symbol detection. Lists symbols removed in recent indexed commits that were not re-added, using WARP graph history only.
- **knowledge_map** — Session knowledge map — answers "what do I already know?" Lists all files and symbols observed this session, flags stale files (changed since last read), and shows directory coverage. Use before reading more files to avoid redundant context consumption.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "graft": {
    "command": "npx",
    "args": ["-y","@flyingrobots/graft"],
    "env": {
      "GRAFT_ROOT_PATH": ""
    }
  }
}
```

**Requires environment variables:** `GRAFT_ROOT_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/flyingrobots-graft/readme_