Spiderbrain MCP server

SpiderBrain: the understanding layer for your repo

A repo tells an AI agent what the code is. It never tells it what matters, what a change reaches, or why anything was built the way it was. So every agent re-derives the structure from scratch, every session, and gets it a little wrong.

SpiderBrain gives a repo a committed, source-free understanding layer: a deterministic map of its structure, dependencies, and blast radius that any AI coding agent can read with zero setup. This repository is the open, MIT-licensed part of that layer: the reader, and the format specification.

• Website: https://spiderbrain.ai
• Determinism benchmark: https://contextbenchmark.com

Use it in one line

When a repo carries a .spiderbrain/ folder, point the reader at it:

npx spiderbrain mcp --root .

An MCP client's working directory is usually not your repository, so pass the repo

explicitly with --root , --root=, or the SPIDERBRAIN_ROOT environment

variable. Without it the server serves the working directory and reports that no

understanding layer was found, which is a wrong answer rather than an error.

That starts an MCP server your coding agent (Claude Code, Cursor, or any MCP client) can query. Tools: sbblast, sbimpact, sbpath, sbkeystones, sbmap, sbask. No account, no SpiderBrain install, no configuration. A real session transcript is in examples/agent-session.md.

Prefer the terminal:

npx spiderbrain blast src/server/health.ts   # what a change here reaches
npx spiderbrain impact                        # what YOUR CURRENT DIFF reaches
npx spiderbrain keystones                     # the load-bearing files
npx spiderbrain map src/auth/session.ts       # what a file is + touches
npx spiderbrain path src/a.ts src/b.ts        # how one file reaches another
npx spiderbrain verify --allow-stale          # folder untampered? see note below

Why --allow-stale on a committed brain. verify checks two things: that

structure.ndjson still matches its recorded fingerprint, and that the brain was scored at

the current HEAD. Committing the folder is itself a commit, so a brain committed to a repo

is always at least one commit behind and the second check can never pass on a fresh clone.

--allow-stale keeps the integrity check strict and tolerates only that. Drop the flag when

you build the brain in CI at the commit you are testing, where currency is real.

Agents are first-class

Every command takes --json and emits one machine-readable object, and exit codes are part of the contract: 0 ok, 1 check failed, 2 usage, 3 no understanding. CI can gate on them:

npx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files
npx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)

Ready-made workflows - a PR blast-radius comment and a freshness gate - are in examples/.

No folder? Registry fallback

When a repo carries no .spiderbrain/ folder, the reader checks the public SpiderBrain registry for an unofficial brain of the same repo (matched by the origin remote, clearly labeled, fingerprint-verified). The committed folder always wins when present; maintainers can publish the official one with npx spiderbrain create.

This repo eats its own dogfood

This repository carries its own committed .spiderbrain/ folder, derived from its real import graph (node scripts/build-own-brain.mjs, regenerated deterministically, verified in CI). Clone it and ask it about itself:

Shortened. The full README is on GitHub.