HeliosDB CodeKB

Local MCP 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. The recommended transport is a loopback HTTP daemon (127.0.0.1) so local clients share one warm embedded KB process instead of starting competing stdio processes.

What this buys you: fewer broad-repo discovery turns, smaller tool payloads, reusable code/doc context across Claude Code and Codex, and evidence-carrying answers instead of ad hoc Read/Grep tours. It is strongest on monorepos and portfolio-scale work where the agent would otherwise repeatedly rediscover the same architecture, docs, and file map.

Published release: 0.2.5 on crates.io. It adds HTTP-first setup, doctor, compact helios(action, args) routing, exact file_lookup / doc_lookup, and repo-inventory fallback for fast portfolio KBs.

Benchmark context: v0.2.1 headline (qwen3-coder:30b on /home/gpc/HDB/Full): −37.2 % model tokens vs no-MCP across 15 dev questions (full report in MCP_ECOSYSTEM_BENCHMARK_REPORT_2026-05-27.md). Biggest single-question wins: −76 k, −69 k, −47 k tokens on broad-architecture queries. See Honest caveats for the workloads where Read+Grep is still cheaper.

On the newer /home/app/Helios portfolio re-test for v0.2.4/v0.2.5, the best full run observed −28.7 % model tokens with a warm loopback HTTP MCP daemon. A later routing run measured −19.4 %. That is still a real improvement, but not a universal win; exact narrow lookups can still be cheaper with raw local search.

Why it improves answer quality, not just token count

The bench measures cost. But the reason MCP wins on broad questions isn't just compression — it's that the wrapper layer gives the model better-grounded raw material to reason from. Every quality lever also reduces tokens; both directions point the same way.

When the plugin earns its keep

Honest caveats

• Direct symbol lookups can still be cheaper through raw Read+Grep when the agent already knows the exact file and only needs a tiny span. The v0.2.4 file_lookup / doc_lookup wrappers remove the worst exact-path regression, but symbol-card coverage still matters for "public types in crate X" style questions.
• Symbol-card population is content-hash-gated. If helios_symbol_card returns {"status": "not_found"}, re-run ingest to backfill the cards. The Full benchmark report has a "Recommended Next Work" section calling out the cases where card coverage matters most.
• Cold-start cost is high on benchmarks because each WITH-MCP run launches a fresh serve subprocess. Real agent sessions keep the server warm; the per-question cold start ratio improves with longer sessions.
• Full portfolio code-graph indexing still has an engine bottleneck. Nano 3.36.1's cross-file resolver can become a long serial phase on very large KBs. Fast ingest mode remains useful for file/doc lookup and GraphRAG, but deep symbol cards need the engine-side resolver work to become adoption-grade on the largest portfolios.
• Engine-side FRs are queued. Four engine improvements would unlock another step-change in both quality and cost — tracked in ENGINE_FRS_FROM_CODEKB_2026-05-26.md. FR #1 (FK validation throughput) is the prerequisite for benching on /home/gpc/HDB-scale (10 k+ files) corpora; FR #4 (tools/list verbose=false) would compose with the existing --mega-tool for even smaller catalogue payloads.

Use the plugin when the cross-modal / time-travel / catastrophe-prevention / answer-grounding value matters. The aggregate token win on broad workloads (−37 % on Full) is a bonus; the per-answer quality lift is the durable value.

Install

Step 1 — install the heliosdb-codekb-mcp binary

cargo install heliosdb-codekb-mcp
# binary lands at ~/.cargo/bin/heliosdb-codekb-mcp

This is the recommended path for every platform (Linux x86_64, Linux aarch64, macOS Intel, macOS Apple Silicon). Current source version and crates.io release: 0.2.5. First build pulls the engine (heliosdb-nano) and is slow (~10 min); subsequent updates are cached.

curl -L \
  https://github.com/HeliosDatabase/HeliosDB-CodeKB-MCP/releases/download/v0.2.3/heliosdb-codekb-mcp-linux-x86_64 \
  -o ~/.local/bin/heliosdb-codekb-mcp
chmod +x ~/.local/bin/heliosdb-codekb-mcp
# Optional but recommended: verify
curl -sL https://github.com/HeliosDatabase/HeliosDB-CodeKB-MCP/releases/download/v0.2.3/heliosdb-codekb-mcp-linux-x86_64.sha256 \
  | sha256sum -c -

git clone https://github.com/HeliosDatabase/HeliosDB-CodeKB-MCP
cd heliosdb-codekb-mcp
cargo build --release --features native-binary-docs
# binary: ./target/release/heliosdb-codekb-mcp

Step 2 — index your project

Once per source-tree you want indexed:

heliosdb-codekb-mcp init --source /abs/path/to/your/project \
  --mode co-located --ingest

co-located puts the KB at <project>/.helios-kb (auto-gitignored). See KB-location modes for global / hybrid.

Step 3 — wire it into your agent

The binary is now ready. Pick your agent below.

This repository also ships ready-to-merge templates under install/ for the /home/app/Helios portfolio KB: install/claude-code.mcp.json and install/codex.config.toml.

Start the local MCP daemon

Run one server per KB and keep it running for all local agents:

heliosdb-codekb-mcp serve --source /abs/path/to/your/project \
  --http 127.0.0.1:8765 --wrapper-cache-size 128

The HTTP transport refuses non-loopback binds by default. To expose it outside the machine, set HELIOS_ALLOW_NON_LOOPBACK_HTTP=1 intentionally and only on a trusted network.

Claude Code (claude-code)

Per-project .mcp.json:

{
  "mcpServers": {
    "helios": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

--mega-tool is the default since v0.2.0, so the daemon advertises the compact one-tool surface automatically unless you explicitly configure profile mode.

As a Claude Code plugin (gets you the /codekb-setup, /codekb-ingest, /codekb-status slash commands + the codekb-pro-features skill on top of the MCP server):

# One-time install from the repo's plugin manifest
claude --plugin-dir /abs/path/to/heliosdb-codekb-mcp

Or, after a plugin marketplace publish: /plugin install heliosdb-codekb-mcp. First run /codekb-setup walks through binary install / embeddings / ingest in one flow.

OpenAI CODEX (codex CLI)

Add the server to ~/.codex/config.toml:

[mcp_servers.helios]
url = "http://127.0.0.1:8765/"

To switch projects, run a different loopback port and add another named server (helios-foo, helios-bar, …). Verify the server is registered with:

codex --print mcp_servers

Then start a session as usual; the helios(action, args) tool should appear in the tool list. If CODEX reports the server is unreachable, run:

heliosdb-codekb-mcp doctor --source /abs/path/to/your/project \
  --mcp-url http://127.0.0.1:8765

Cursor / Continue / other MCP clients

heliosdb-codekb-mcp serve --source /abs/path \
  --http 127.0.0.1:8765 --wrapper-cache-size 128

Then point the client at:

The HTTP gateway honours --mega-tool, --profile, and --strip-tool-descriptions the same way the stdio path does.

Step 4 — verify

heliosdb-codekb-mcp status --source /abs/path/to/your/project

You should see kb-on-disk : exists and a non-zero row count. If status reports an interrupted ingest, just re-run heliosdb-codekb-mcp ingest --source <path> — the checkpoint resumes from the last completed phase.

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 local MCP server. serve --source <PATH> opens an EmbeddedDatabase rooted at that source's KB. Prefer --http 127.0.0.1:<port> for Claude Code/Codex multi-session use; stdio remains available as a fallback. Most query tools (helios_lsp_*, helios_graphrag_search, helios_ast_diff, …) come from the engine library, while this binary owns config, transport, compact wrappers, and answer-card shaping.

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).

Day-2 operations

After Install:

# Refresh the KB after meaningful source changes
heliosdb-codekb-mcp ingest --source /abs/path/to/your/project

# Inspect / sanity-check
heliosdb-codekb-mcp status                              # global summary
heliosdb-codekb-mcp status --source /abs/path           # per-KB row counts
heliosdb-codekb-mcp status --source /abs/path \
    --mcp-url http://127.0.0.1:8765                     # live cache stats (HTTP mode)
heliosdb-codekb-mcp config show                         # raw TOML config

# Re-ingest with LLM distillation (one-sentence symbol summaries via
# a self-hosted Ollama / qwen3-coder endpoint). Opt-in; slow first
# pass, incremental after.
heliosdb-codekb-mcp ingest --source /abs/path \
    --with-llm-distill \
    --llm-distill-endpoint http://ollama:11434 \
    --llm-distill-model qwen3-coder:30b \
    --llm-distill-batch-size 8

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.