mcp-code-index 0.1.0

SQLite-backed code index for Claude Code, exposed via MCP

code-index

A SQLite-backed code index for Claude Code, exposed via MCP. Replaces exploratory Read/Grep/Glob calls with targeted retrieval.

What it does

• Parses your repo with tree-sitter (Python, TypeScript/JavaScript, Go, Rust).
• Chunks per symbol; expands identifiers (getUserAuthToken → get user auth token).
• Embeds with Voyage voyage-code-3 (default) or local Ollama.
• Stores symbols, chunks, vectors, and call/import edges in .claude/index.db.
• Serves retrieval over MCP — 8 retrieval tools + 1 admin tool (see below).
• Auto-updates via a Claude Code PostToolUse hook and an optional file watcher.

Tools

Tool	Purpose
init	Build or refresh the project's index. Incremental by default; force=true rebuilds from scratch.
code_search	Hybrid (vector + FTS) search for conceptual queries (e.g., "auth flow", "where do we parse JSON").
symbol_lookup	Exact-name lookup of functions / classes / methods / types. Prefer over code_search for identifiers.
file_outline	Symbols (with signatures) in a file, in source order. Use instead of Read when you only need shape.
get_symbol_body	Full chunk for a symbol_id returned by symbol_lookup or code_search.
callers	Symbols that CALL the given symbol. depth (1-5) expands transitively.
callees	Symbols that the given symbol CALLS. depth (1-5) expands transitively.
dependents	Files that import the given file.
dependencies	Files that the given file imports.

All tools return bounded JSON; large bodies use get_symbol_body rather than inlining whole files.

Requirements

Python with loadable SQLite extension support (required by sqlite-vec). Python 3.13 has this enabled by default. For 3.10–3.12, use either:

• the python.org installer, or
• pyenv: PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x

Install

In Claude Code (primary)

# 1. Set your embedder API key (Voyage default; for local Ollama see Configuration)
export VOYAGE_API_KEY=...

# 2. Register the MCP server. uvx clones, builds, and runs — no global install.
claude mcp add code-index -- uvx --from git+https://github.com/achreftlili/code-index code-index-mcp

That's it. Open Claude Code in your repo and ask:

"Build the code index for this repo."

Claude calls the init MCP tool, which writes .claude/index.db. Subsequent prompts can use code_search, symbol_lookup, callers, etc. — see Tools above for the full surface.

Or, with a permanent install

pip install mcp-code-index
claude mcp add code-index -- code-index-mcp

Optional: keep the index live as you edit

Without the hook below, the index drifts when files change outside the agent (mv, git checkout, IDE saves) until you call init again. With it, every Edit / Write / MultiEdit Claude performs triggers an incremental reindex of the touched file:

git clone https://github.com/achreftlili/code-index ~/code-index
~/code-index/scripts/install-hook.sh /path/to/your/repo   # idempotent

In other MCP-compatible agents

The server speaks standard MCP over stdio, so any client that supports MCP servers works (Cursor, Continue, Cody, Zed, etc.). Configure the client to launch code-index-mcp (after pip install) or the uvx --from git+… command above. Once connected, call the init tool from inside the client to bootstrap the index.

From source (development)

git clone https://github.com/achreftlili/code-index
cd code-index
pip install -e .
code-index init        # CLI alternative to the `init` MCP tool
code-index-mcp         # starts the MCP server on stdio (for manual wiring)

Configuration

Environment variables:

Var	Default	Notes
CODE_INDEX_DB	.claude/index.db	SQLite path.
CODE_INDEX_EMBEDDER	voyage	voyage or ollama.
CODE_INDEX_EMBED_MODEL	voyage-code-3	Model name.
CODE_INDEX_EMBED_DIM	1024	Must match the model.
VOYAGE_API_KEY	—	Required when CODE_INDEX_EMBEDDER=voyage.
OLLAMA_URL	http://localhost:11434	Ollama server.

Layout

src/code_index/
  db.py           SQLite schema, connection, sqlite-vec loading
  parser.py       Tree-sitter wrapper, symbol + edge extraction
  chunker.py      Per-symbol chunks, identifier expansion
  embedder.py     Voyage / Ollama backends
  indexer.py      Pipeline: walk → parse → chunk → embed → write
  retriever.py    Hybrid search (vector + FTS5) with RRF
  watcher.py      File watcher (watchdog)
  mcp_server.py   8 MCP tools
  cli.py          init / reindex / watch / stats