amdb: A Local, Single-Binary MCP Server That Turns Your Codebase Into AI Context

As AI coding assistants become more powerful, the problem of feeding them the right context from your codebase has grown acute. Most solutions ship context to the cloud, which is a non-starter for air-gapped environments, regulated industries, and anyone wary of sending proprietary code to a third-party API. amdb, a new open-source project, takes a different route: it builds a local, searchable index of your codebase and serves it to MCP-compatible AI tools entirely on your machine.

The project describes itself as a "zero-runtime, single-binary code context MCP server with combined graph + vector retrieval." That means there's no Node.js or Python runtime to install — just a compiled binary you download or build from source. It's built for exactly the scenarios where cloud-based indexing is prohibited: air-gapped networks, CI containers, and regulated industries.

How It Works

amdb works in two phases. First, you build the index with amdb init. This parses every source file using Tree-sitter, extracts symbols and call edges, and embeds each symbol with a local fastembed model. Content hashing ensures unchanged files are skipped on re-runs, so incremental updates are cheap. The data lands in two SQLite files: one for symbols and relationships, one for vectors.

Once the index is built, the server exposes three MCP tools that read from it. Retrieval combines exact name matching, cosine similarity over vectors, and call-graph expansion. If no index exists, the tools respond with an error telling you to run amdb init — the server never indexes on its own, keeping it lightweight and predictable.

You can also skip the server entirely and generate a context file directly:

amdb generate --focus "auth"

This writes a targeted Markdown file to .amdb/, giving you a snapshot you can paste into any AI tool.

Performance and Honesty

The README includes a benchmark against amdb's own source tree (31 files, ~21,900 tokens). The headline result: 1.0 seconds end-to-end for a real session. But the project is refreshingly honest about the tradeoffs at small scale. On a 31-file repo, grep is genuinely competitive on token count. amdb's edge is one structured call instead of two to four, with signatures, visibility, and resolver-accurate caller/callee attribution instead of raw text.

The token gap widens with repo size: a full dump grows linearly, grep grows with match noise, while amdb's focus output grows only with the size of the relevant interface. That's the real sweet spot — large codebases where context selection matters.

Setup and Usage

For VS Code or Cursor, add a .vscode/mcp.json to your project. The server speaks MCP over stdio, which makes it compatible with any MCP client. There's also a daemon mode (amdb daemon) that watches the project and incrementally re-indexes on save.

For containerized environments, the Docker image speaks MCP over stdio immediately. Note that the published ghcr.io/betaer-08/amdb:1.0.0 image runs bare amdb, so you need to pass the serve subcommand explicitly. Images from the next tag will default to serve.

The Bottom Line

amdb is an MIT-licensed, single-binary MCP server that brings a serious architectural idea to the table: codebase context can be extracted, indexed, and served entirely locally without sacrificing retrieval quality. It even supports 16 grammars for symbol extraction, though full signature enrichment is AST-accurate for only three languages — the project documents this clearly in a table, so you know what you get.

For developers working in regulated industries, or anyone who simply prefers to keep their code on-prem, amdb is worth a look. It's a reminder that not every AI feature needs to phone home.