heliosdb-codekb-mcp

MCP stdio server for code+docs knowledge bases. Embeds HeliosDB-Nano as a Rust library (code-graph, graph-rag, mcp-endpoint, code-embed features) and exposes its LSP-shaped + GraphRAG tools to Claude Code, Cursor, Codex, Aider, and any other MCP-aware agent — over plain stdio JSON-RPC, no ports, no auth dance, all local.

What this plugin actually buys you

Measured on a real corpus (see bench/README.md), the value proposition is not "saves N % tokens on every query." The honest picture across 10 typical dev questions × multiple trials with both Haiku 4.5 and Opus 4.7:

What the plugin does NOT do well (yet):

• It is not consistently cheaper than Read+Grep on simple symbol lookups with a small model. The bench shows 1.5-2× run-to-run variance and the median is roughly even with no-MCP after three Haiku trials.
• helios_lsp_* and helios_graphrag_search default to returning rich context (neighbouring symbols, full doc-section bodies). The plugin ships an opt-in --max-tool-result-bytes trimmer, but blunt trimming costs more than it saves on this workload — the agent treats the …[truncated] marker as a Read-fallback signal.
• The biggest win-back lever — having the engine expose verbose: false modes for each tool — lives engine-side. Tracked in bench/README.md "follow-up hypotheses".

Use the plugin when the cross-modal / time-travel / catastrophe-prevention value matters. Don't deploy it expecting token savings on a Haiku Q&A workload.

Install

Pre-built binary (recommended)

Latest release: v0.1.0

curl -L \
  https://github.com/dimensigon/heliosdb-codekb-mcp/releases/download/v0.1.0/heliosdb-codekb-mcp-linux-x86_64 \
  -o /usr/local/bin/heliosdb-codekb-mcp
chmod +x /usr/local/bin/heliosdb-codekb-mcp

Verify with the matching .sha256 from the release page.

From source (any platform)

cargo build --release --features native-binary-docs
# binary: ./target/release/heliosdb-codekb-mcp

Use as a Claude Code plugin

This repo ships a .claude-plugin/plugin.json manifest plus three slash commands (/codekb-setup, /codekb-ingest, /codekb-status) and a codekb-pro-features skill. Install for a single Claude Code session:

claude --plugin-dir /abs/path/to/heliosdb-codekb-mcp

Or fetch directly from a release/branch URL once distributed via a plugin marketplace. On first use, run /codekb-setup — it walks you through the binary install (if needed), asks whether to enable the optional one-time ~30 MB embeddings download, and indexes the current project.

The plugin's .mcp.json declares the MCP server with --source ${CLAUDE_PROJECT_DIR}, so the helios MCP tools follow whichever project Claude Code is opened in.

What it is

Three things at once:

1. A user-level config tool. Run init --source <PATH> --mode <co-located|global|hybrid> once per source-directory you want indexed. The choice persists in ${XDG_CONFIG_HOME:-~/.config}/heliosdb-codekb-mcp/config.toml.
2. A KB resolver. Given a source path, finds the right KB directory using the persisted config (with longest-prefix match for hybrid setups that span multiple sub-trees).
3. The MCP stdio server. serve --source <PATH> opens an EmbeddedDatabase rooted at that source's KB and runs heliosdb_nano::mcp::McpServer::new(db).run().await. All query tools (helios_lsp_*, helios_graphrag_search, helios_ast_diff, …) come from the engine library — this binary owns transport and config, not tool surface.

KB-location modes

Document ingestion (default tier — no Docling)

Out of the box, ingestion uses pure-Rust crates. Single static binary, no Python, no Docker. Covers ~80% of real-world content:

Document ingestion (--features docling)

Build with --features docling and the binary additionally routes:

This tier requires a docling-serve HTTP endpoint to be running (host-managed, or via the helios-code-graph plugin's bundled compose stack).

Quickstart

# 0. Build
cargo build --release
BIN=$(realpath target/release/heliosdb-codekb-mcp)

# 1. Configure a KB for a source path AND do the first ingest in one shot
$BIN init \
    --source /home/me/my-repo --mode co-located \
    --ingest

# 2. Wire the MCP server into your agent.  For Claude Code (.mcp.json):
{
  "mcpServers": {
    "helios": {
      "command": "/abs/path/to/heliosdb-codekb-mcp",
      "args": [
        "serve", "--source", "/home/me/my-repo",
        "--mega-tool", "--wrapper-cache-size", "128"
      ]
    }
  }
}

# Or HTTP transport (Cursor / Continue / any non-stdio client):
$BIN serve --source /home/me/my-repo --http 127.0.0.1:8765

# 3. Inspect / sanity-check
$BIN status                                           # global summary
$BIN status --source /home/me/my-repo                 # per-KB
$BIN status --source /home/me/my-repo \
    --mcp-url http://127.0.0.1:8765                   # + live cache stats
$BIN config show                                      # raw TOML

Ingest tiers

Three knobs, picked at init --ingest or ingest time, scaling quality vs. wall time on the pilot corpus (~/Helios/Nano, 666 files / 18 k symbols / 115 k refs):

Recommended for repos >~1 000 files: --background-quality. Track via status --source X ("quality phase : running pid X" → "complete — took Y").

Resume on interrupt

ingest writes <kb_dir>/.ingest-state.json at each phase transition (walk → code_index → graph_rag). If a process is killed mid-flight (Ctrl-C, OOM, reboot), the next ingest reads the file at startup and skips already-completed phases — the walk is skipped if phase >= code_index. Per-file resume inside code_index is the engine's content-hash gate. Cleared on successful completion; surfaced by status --source X as ingest resume : interrupted at phase = ... until then.

Generated-file skip

Two layers, both honoured during the walk:

• @generated content-marker scan of the first 4 KiB (Facebook / Google / Bazel / Go convention).
• <root>/.gitattributes linguist-generated globs — patterns flagged with linguist-generated, linguist-generated=true, or linguist-generated=set are matched against relative paths and skipped. Long-tail coverage of generated files (*.pb.rs, codegen/**, vendored bundles) that don't carry an in-file marker.

CLI surface

heliosdb-codekb-mcp <SUBCOMMAND>

  init     [--source PATH] [--mode co-located|global|hybrid] [--kb PATH]
           [--ingest] [--include-binary-docs BOOL]
           [--force] [--durable-writes]
           [--with-embeddings] [--background-quality]

  ingest   [--source PATH] [--include-binary-docs BOOL]
           [--force] [--durable-writes]
           [--with-embeddings] [--background-quality]

  serve    [--source PATH] [--http <ADDR>]

  status   [--source PATH] [--mcp-url <URL>]

  config   show | set-default-mode <MODE> | path

Why a separate binary

HeliosDB-Nano is a generic database; baking one specific MCP transport into its binary would adapt the engine to one consumer. This crate keeps that boundary clean: the engine stays generic and publishable to crates.io for any downstream consumer; this binary holds the MCP packaging, transport, and per-source KB-location ergonomics.

License

Apache-2.0.