Spiderbrain

What Spiderbrain MCP server does

Spiderbrain MCP server gives coding agents access to a repository understanding layer stored in .spiderbrain/. The layer records source-free information about file paths, structure, dependencies, and derived blast-radius relationships. It does not contain the repository’s source code or scoring weights.

The reader can answer which files a change may reach, which files are load-bearing, how one file connects to another, and what a file touches. Results are deterministic when they come from the same committed understanding data: the same repository state and question produce the same answer. Each folder includes a fingerprint that the reader checks so edited or corrupted data is detected.

How it works

Start the MCP process with the Spiderbrain CLI and point it at the repository that contains .spiderbrain/. The server exposes six agent tools: sb_blast, sb_impact, sb_path, sb_keystones, sb_map, and sb_ask. Commands and tools return structured information suitable for coding agents; the CLI also supports --json for machine-readable output.

The local reader works offline for structure, dependency, blast-radius, and keystone queries. If the repository has no local understanding folder, it can check the public SpiderBrain registry for an unofficial, fingerprint-verified brain matched using the repository’s origin remote. A local committed folder takes precedence.

Cloud features require an API key. They add recorded reasoning for a file, current scores, and semantic search; these are separate from the deterministic offline queries.

Setup and configuration

Install or run the package through npx:

npx spiderbrain mcp --root /path/to/repository

The --root option is important because an MCP client’s working directory may not be the repository being queried. The same location can be supplied as --root=<path> or with SPIDERBRAIN_ROOT. Without an explicit root, the process examines its working directory and reports that no understanding layer was found if .spiderbrain/ is elsewhere.

No account, local SpiderBrain installation, or additional MCP configuration is required for the reader. To create a local understanding folder from the cloud service, set SPIDERBRAIN_API_KEY and run npx spiderbrain create; that workflow also writes an AGENTS.md block. Commit the generated .spiderbrain/ folder if agents should use it later.

Tools and capabilities

• sb_blast: inspect the files reached by changing a specified file.
• sb_impact: inspect the likely reach of the current diff.
• sb_path: trace how one file reaches another.
• sb_keystones: identify load-bearing files in the repository.
• sb_map: view what a file is and what it touches.
• sb_ask: ask questions against the available understanding layer.

The command-line interface provides corresponding operations such as blast, impact, path, keystones, map, and verify. Exit codes distinguish successful queries, failed checks, usage errors, and a missing understanding layer. CI workflows can use options such as --fail-over to reject a change whose blast radius exceeds a threshold.

Limitations and notes

Spiderbrain MCP server reads the published understanding data; it does not reconstruct the repository’s source code during a query. Answers are limited by the files and relationships captured in the layer. A committed folder is normally behind the current commit because committing the folder creates another commit, so verify --allow-stale permits that specific freshness condition while retaining the integrity check. Use verify without that flag when the brain was generated for the exact commit under test.

The scoring engine that produces the brain is proprietary. The open packages provide the folder specification, reader, MCP server, and producer client. The project and its packages are MIT licensed.