5 min read · by Ankur Halder

Run codebase-snapshot as an MCP server

codebase-snapshot mcp serves a repository to any Model Context Protocol client over stdio. It is one command, no configuration, and it is the snapshot — not a directory walk — that the client sees.

Available from 0.9.4. Run npx codebase-snapshot --version before wiring a client; anything older does not have the mcp command.

Start it

npx -y codebase-snapshot@0.9.6 mcp

The server serves the directory it was started in. --cwd <path> points it elsewhere, and that directory is the only one it will read.

A client needs two things: the command npx and the arguments above. The surrounding configuration shape belongs to the client — the example below is the mcpServers form used by Claude Desktop and Cursor:

{
  "mcpServers": {
    "codebase-snapshot": {
      "command": "npx",
      "args": ["-y", "codebase-snapshot@0.9.6", "mcp", "--cwd", "/absolute/path/to/repo"]
    }
  }
}

Claude Code registers the same thing from a shell:

claude mcp add codebase-snapshot -- npx -y codebase-snapshot@0.9.6 mcp --cwd /absolute/path/to/repo

On Windows, wrap the command as cmd /c npx with the same arguments — npx is a .cmd shim there, and clients that spawn without a shell cannot execute it directly.

The seven tools

Six are declared readOnlyHint, which most clients use to run them without asking. Only snapshot_generate prompts.

snapshot_locate is the one that makes the others usable: a twelve-part snapshot is hundreds of kilobytes, and asking "which part holds authentication?" is cheaper than reading all twelve. It searches the manifest's index — file paths, exported symbols, component names, routes, layers and kinds — and returns the part each match lives in.

snapshot_read is windowed on purpose. It defaults to 200 lines and reports nextFromLine when more remains, so an agent continues deliberately instead of pulling a whole part into a context window it has not budgeted.

Resources

Resources are the browse surface; tools are the act surface.

Part resources carry their size in the description, so a client choosing between them can see that one is 300 kB before attaching it.

Prompts

Two, both about order of operations rather than features: orient maps the repository before anything is read, and keep-current validates before trusting earlier context and again after making changes.

What it will not do

• Read outside its root. --cwd is the only directory that is readable. A root argument can name a sub-directory of it and nothing else; symlinks are resolved before the check.
• Emit a sensitive file. .env, *.pem and the rest stay out, and includeSensitiveFiles is not a tool argument — a prompt cannot ask for it. Reads come from the emitted snapshot, so redaction applies to everything the client sees.
• Install or configure. snapshot_generate writes the snapshot directory and nothing else. It never runs a package manager and never writes a config file.
• Touch the network. The server makes no outbound connections, and there is no HTTP transport.

Both protocol eras

Revision 2026-07-28 removed the handshake that every client in use today still performs. The server speaks both and answers whichever arrives first.

The two disagree about an unsupported version, and the difference is observable: a legacy client is negotiated down to a revision the server speaks, while a modern client receives -32022 with the list of supported revisions so it can retry.

Why there is no SDK

@modelcontextprotocol/sdk is 4.5 MB unpacked and brings Express, Hono, Ajv, JOSE and Zod with it. The transport here is newline-delimited JSON-RPC, which is roughly 400 lines of readable code, and the package's only runtime dependency remains typescript. The parity test — a live tools/list compared against describe --format json — is what keeps the protocol implementation honest, not the presence of a library.

Performance

Generation is synchronous, so a tool call blocks the server for its duration. Both numbers are measured, not estimated:

Both are under any client's request timeout. If a repository large enough to exceed yours shows up, snapshot_plan gives the same numbers without writing, and the fix — moving generation to a worker thread — is tracked rather than assumed.

Troubleshooting

The client lists no tools. The server writes JSON-RPC to stdout and nothing else; every note goes to stderr. Check the client's server log — the first line says which directory is being served.

Unknown tool or a missing command. The published version is older than 0.9.4. Pin the exact version in the client arguments.

Unknown resource for a part. Resources are computed from the manifest, so nothing but the static set exists before the first generate. Call snapshot_status, then snapshot_generate.

A file is missing from snapshot_locate. It is excluded, and snapshot_explain will name the reason — an ignore rule, the preset, a sensitive-file pattern, or your own config.