Sonde MCP server

Sonde

A local code-context engine for AI coding agents. Sonde indexes a TypeScript, Python, or Swift repository into a symbol-level graph in SQLite and exposes three MCP tools — findsymbols, querygraph, and getimpactradius — so an agent can answer who calls this, what breaks if I change it, and which tests relate to it in one call instead of a search loop.

What the benchmark actually shows

The honest claim is not "finds what grep cannot". A competent agentic search loop finds the same structural evidence — we measured it, on a real 19,409-line repository, and it scored 1.000 recall on every task.

The claim is the same answers for a fraction of the cost, inside a budget:

Sonde matches the baseline's answers on every structural task while using ~3× less context, 8× fewer calls, and ~147× less wall-clock time — and it never exceeds the caller's token budget, because the packer truncates to it by construction. That is the trade being offered.

Where it loses. Behavioural queries with no shared vocabulary — "where is the retry backoff decided?" — score 0.00. Local semantic retrieval was built and measured and does not fix it (see the design doc §2.2); the capability is therefore not claimed. If your questions are mostly of that shape, an agentic search loop is the better tool today.

Numbers are reproducible: npm run bench:fixture && npm run bench:large. Full results in BENCHMARK-LARGE.md and BENCHMARK.md.

Install and run

npm install -g @cheppulabs/sonde
cd your-project
sonde init

sonde init indexes the repository and registers sonde as an MCP server in this project's .mcp.json, asking before it writes anything (skip the prompt with sonde init --yes). It never touches an .mcp.json it can't safely merge into — an existing sonde entry that differs from what init would write is left alone and reported, not overwritten.

For Python repositories, use sonde init --resolve; the default tree-sitter tier did not pass the project's placement gate for structural queries.

Equivalent by hand, if you'd rather see every step:

sonde index .
# then add to .mcp.json:
# { "mcpServers": { "sonde": { "command": "sonde", "args": ["mcp", "serve", "."] } } }

No account or hosted service is required.

Architecture documentation

sonde doc writes an ARCHITECTURE.md describing the repository's modules, how they depend on each other, and what each one exposes — generated from the graph, so it reports what the code actually does rather than what someone remembered.

sonde doc            # write ARCHITECTURE.md
sonde doc --stdout   # print it instead
sonde doc --check    # fail if it is out of date (for CI)
sonde doc --module src/store   # symbol-level detail, never committed

It is meant to be committed and regenerated, not hand-edited. Regeneration is byte-identical when nothing changed, so it does not churn your diffs; when two branches both regenerate it, resolve the conflict by running sonde doc again rather than merging by hand. It refuses to overwrite an ARCHITECTURE.md it did not generate.

Three things it deliberately does not do:

Shortened. The full README is on GitHub.