@prom.codes/context-mcp

prom.codes Context — local-first codebase indexing & retrieval as an MCP server (stdio).

Quick start (Claude Code)

claude mcp add context --env PROMETHEUS_API_KEY=prom_live_… -- npx -y @prom.codes/context-mcp@latest

claude mcp add defaults to local scope (just you); add --scope project to write a committable .mcp.json, or --scope user for all your projects. Other MCP hosts (Cursor, VS Code) use the same command/args in their own config.

Configuration

• PROMETHEUS_API_KEY (required for semantic search) — a real key minted at app.prom.codes/app/api-keys, shape prom_live_<tag>_<secret>. Embeddings route through the managed prom.codes proxy — you never bring your own provider key. Without a valid key, code search degrades gracefully to lexical (keyword) + symbol-graph retrieval (no embeddings needed) and every structural tool still works.
• Workspace root is auto-detected — no need to set PROMETHEUS_WORKSPACE_ROOT. Claude Code passes the open project via CLAUDE_PROJECT_DIR; Cursor/VS Code via the MCP roots capability. Set it only to point at a different folder.
• The index is a local SQLite DB at ~/.prometheus/<hash>.db (one per project). Your code never leaves your machine — only embedding text transits to the proxy.
• Won't crawl your home folder — or your whole code directory. If a fresh window/terminal opens with no project, the workspace falls back to the host cwd (often home, or the parent folder holding all your repos); the server refuses to auto-index the home directory, a filesystem root, or a folder that merely CONTAINS many projects, and leaves the index empty until you open one real project. A real project/monorepo (has .git/package.json/… at its root) is always indexed. PROMETHEUS_INDEX_ROOT_OK=1 forces an unconventional root. Call index_status to see what's going on.

Tools: search_code, get_symbol, find_references, find_callers, find_callees, expand_context, get_file, list_changed_since, list_workspaces, framework_overview, get_architecture (one-call codebase map — index size, languages, frameworks, packages, folder layout, symbol-kind breakdown, most-referenced hotspots, entry points; the fast first move on an unfamiliar repo), index_status (health check: which folder, how much is indexed incl. embedding coverage %, does the key work, is an update available?), reindex (rebuild/repair the index on demand), install_hooks (see Awareness), dashboard (render a local HTML status page: running servers via heartbeats, per-workspace index health + embedding coverage, memory, hooks/key, cloud usage), and update_servers (safe, guided self-update of all three prom.codes servers — never installs while servers are running; a detached updater waits for the windows to close, or terminates them with force: true).

Awareness

The server advertises MCP instructions that tell the agent to PREFER search_code + the graph tools over a manual grep→read loop. Context tools are reactive (the agent reaches for them when it needs code), so — unlike memory — no rule file is installed; the instructions + assertive tool descriptions are enough to win over plain grep on a large or unfamiliar repo.

If passive instructions still aren't enough (agents defaulting to grep out of habit), call the install_hooks tool to add Claude Code session hooks that actively enforce it: a SessionStart hook injects a binding 'call memory_read; use search_code before grep' directive at turn 0 (and after every compaction) and a UserPromptSubmit hook re-asserts it per prompt. scope: user (default, all projects) or project; strict: true also denies Grep/Glob and redirects to search_code (opt-in); uninstall: true reverts. Idempotent, backs up settings.json, Claude-Code-specific. index_status reports whether they're on.

Native modules — no install script needed

Uses native Tree-sitter grammars + better-sqlite3, but nothing is built on your machine and no install script runs. The SQLite addon ships prebuilt in a platform package (@prom.codes/native-<platform>) listed as an optional dependency: npm picks the one matching your os/cpu/libc and installs it by copying files. The Tree-sitter packages carry their own prebuilt binaries and resolve them at require time.

So a hardened npm needs no special handling: ignore-scripts=true — a sensible policy, and npm v12's default — has nothing left to suppress. No flags, no compiler, no allow-list:

npm install -g @prom.codes/context-mcp

Prebuilt for macOS / Linux (glibc + musl) / Windows on x64 + arm64, Node 22, 24, 25 and 26. Requires Node ≥ 22 — upstream better-sqlite3 publishes no prebuild for Node 20's ABI. On an unshipped combination the install still succeeds and falls back to building from source, which needs install scripts allowed (--allow-scripts=better-sqlite3,tree-sitter, npm ≤ 11: --ignore-scripts=false --foreground-scripts) and C/C++ build tools.

Docs: https://prom.codes/docs/mcp/claude-code