mcp-code-indexer
Summary: The supplied schema exposes project lifecycle, indexing, and semantic-search tools, though it conflicts with the README's stated read-only MCP surface.
Register a project and start initial indexing (
add_project).Remove a project and delete its Qdrant collection, manifest, and registry entry (
remove_project).List registered projects with index summaries and staleness (
list_projects).Run semantic code search, optionally limited and filtered by project/file path (
semantic_search; schema says it checks staleness and incrementally reindexes first).Check indexing state and last-pass progress (
index_status).Force a full rebuild of a project index (
reindex_project).README contradiction: it says the documented MCP server is read-only and excludes
add_project,remove_project,index_status, andreindex_project; writes and repairs are CLI-only.
Uses a LAN-local Ollama instance for generating code embeddings (default qwen3-embedding:8b, 4096-dim), enabling semantic indexing and search of local project directories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-code-indexer search my ~/code/api project for where auth tokens get validated"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
code-indexer
Code index for agents: a one-shot CLI (code-indexer, typer) and an MCP
stdio server (code-indexer-mcp) that is a thin wrapper over that same
CLI: every MCP tool builds the argv of the matching code-indexer
subcommand and runs it, relaying its output -- one code path, so the two
surfaces can never diverge. Structural, lexical and graph queries run off a
SQLite manifest and need no service at all; the optional semantic
extension adds Ollama embeddings (qwen3-embedding:8b, 4096-dim) and one
Qdrant collection per project. Fully LAN-local; no cloud.
An index pass needs no service. add-project writes files, symbols,
references, imports and chunk text and records vectors=off unless asked
otherwise; --vectors on embeds from the stored chunk text without reparsing
a file, and a later pass can do it with the sources unreadable. The vector
store keeps no chunk text: answers read it from the manifest.
Agents never index anything themselves. A read command never refreshes the
index: semantic-search reports whether the index is fresh, stale or
unknown, and repairs it only when the call asks for --refresh (or when a
pass command runs). Chunks, hashes, and collections are never exposed.
The agent surface
The documentation an agent loads is split by what it needs before it can choose a command and what it needs after. The entry document is small on purpose -- 120 lines and 8 KiB, enforced by the test suite, because an agent's context is the resource being spent -- and each reference is read on demand, when its trigger fires.
Document | Open it when |
always first: decision tree, the generated command roster with each command's read-or-write class, the exit table, the staleness rule, the reference index | |
the task is to build or repair an index, or to ask what state one is in | |
a query answered the wrong shape and its flags need reading | |
a question is asked in words rather than as a name, or a ranked answer's order needs reading | |
the task is to change code through a plan | |
an agent parses output instead of reading prose | |
a command failed and the remedy is not obvious from its line |
The command roster and each reference's per-command sections are generated
from the CLI registry by scripts/generate_skill_docs.py, so a command
cannot exist undocumented and a flag cannot be documented that does not
exist; the prose around them is written by hand. tests/test_docs.py fails
when the roster and the registry disagree, when a reference grows past its
budget, when a generated block was hand-edited, or when the installed copy of
the skill differs from the tracked one. The tracked skill/ directory is
already the shape the installer wants: skill/SKILL.md and skill/references/
are copied into the profile's skills root as code-indexer/SKILL.md and
code-indexer/references/, which is why the reference links inside the entry
document are relative to it and resolve in both places.
This README is the overview for the human who installs the tool; each fact lives in exactly one place.
Related MCP server: qdrant-codebase-mcp
Installation (CLI)
From the repo directory, install the CLI as an editable uv tool (on PATH
in ~/.local/bin, edits to the checkout take effect immediately):
uv tool install -e . # core: no service, no MCP server
uv tool install -e ".[semantic]" # + Ollama and Qdrant clients
uv tool install -e ".[mcp]" # + the code-indexer-mcp serverCore installs and runs with no service of any kind -- including indexing.
The semantic extension (OLLAMA_URL, QDRANT_URL) is needed only for
embedding and semantic search; the MCP server ships only with the mcp extra
and is imported by that entry point alone. Verify with
code-indexer list-projects.
Quick start
code-indexer add-project /path/to/repo # register + initial index (foreground, no service needed)
code-indexer add-project /path/to/repo --vectors on # ...and embed into Qdrant
code-indexer semantic-search "auth token refresh" --project /path/to/repo --format compact
code-indexer overview --project /path/to/repo # project map for orientation
code-indexer index-status --project /path/to/repo # indexing state
code-indexer watch /path/to/repo --background # keep the index fresh (opt-in)index-status and the lifecycle commands (reindex-project,
remove-project, lookup-project, index-more) accept the project as
--project / --name or as a positional path. For reindex-project,
remove-project and lookup-project the flag wins when both are given;
index-more accepts <project> <subpath> or --project <project> <subpath>
and rejects the flag plus two positionals as ambiguous. The mutating commands
never guess a project from the cwd.
The agent workflow (overview → skeleton → search → get-code-context) is in SKILL.md, and the flags behind each step are in query.md for the structural reads and semantic.md for the meaning-shaped search.
Architecture
Index: tree-sitter AST chunks (function/class-level, symbol names, schema v7 identity -- qualified names and declaration hashes -- with stored signatures/visibility) with contextual headers, embedded via Ollama into one Qdrant collection per project (
idx_<slug>/idx_<name>).Manifest (SQLite, WAL): files, chunks, content hashes, symbol index, FTS5 lexical table, index fingerprint.
CLI (
code-indexer): every operation, one-shot, foreground; per-project flock serializes concurrent passes.MCP server (
code-indexer-mcp,code-indexer[mcp]only): a narrowed, read-only view over the same CLI subprocess; all foreground, no store or manifest access of its own.Agent surface: one entry document,
skill/SKILL.md, plus six references underskill/references/beside it, with the command sections generated from the registry.
CLI ↔ MCP parity
The MCP surface carries the read-only query shapes and nothing else. Every
tool is one CLI subcommand; code-indexer-mcp --help prints this list from
the server's own registry, so it cannot go stale.
CLI subcommand | MCP tool |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Removed from the surface -- use the CLI subcommand of the same name:
add-project, index-status, lookup-project, reindex-project,
remove-project, changed-symbols, deps, find-callees, find-symbols,
find-definition and outline. Writes are exactly what an MCP client should
not trigger by a call that carries no preview, and the removed reads
duplicate a kept tool's shape or the CLI.
CLI-only (no MCP tool): index-more, doctor, watch, unwatch,
sweep-orphans, eval, eval-compare.
Every tool is a read: readOnlyHint=True with idempotentHint=True is a
claim about what a client sees, and it holds because reads never repair the
index and the relay reports a failure as a failure. A successful call
returns the CLI's stdout as its content; a failing call returns the CLI's
stderr with isError: true and the numeric exit code plus its ErrorType in
the structured result. Nothing is synthesized over a nonzero exit.
MCP options are a subset of CLI flags; the tool schemas (see
src/code_indexer/server.py) are the source of truth for what each tool
accepts. There is no MCP watch/unwatch: a watcher makes no sense inside
an already long-lived server. The server resolves the CLI from
CODE_INDEXER_BIN, else code-indexer on PATH, else
python -m code_indexer.cli; CODE_INDEXER_BIN is the only env var the
server process reads itself -- all other configuration flows through the CLI
subprocess's inherited environment.
Usage record. Every tool call appends one line to
$INDEX_ROOT/mcp-usage.jsonl (~/.code-indexer/mcp-usage.jsonl by
default): tool name, outcome, exit code, response bytes, duration and a
timestamp. Nothing else, and never the arguments -- a query string may be
source code. The line is written by the MCP process, never by a CLI read
command, and a failed write does not fail the call.
Index states
Canonical states, the same everywhere (CLI and MCP):
State | Meaning | Agent action |
| indexed, no pass running | normal use |
| a pass is running | wait/retry |
| registered but no completed pass (interrupted | do not trust empty results; tell the owner |
| index built with a different embed model/dimension/text format/chunker/extraction version | do not run |
| last pass failed | run |
index-status reports the pass state as state=, and -- when the index
was built by a different configuration -- adds fingerprint=needs-reindex reason=..., the same verdict list-projects/doctor give. A project that
owes a rebuild therefore never reads as plainly idle, and the two surfaces
never contradict each other. On such an index the surfaces that answer from
stored rows refuse rather than answer -- find-symbol, find-definition,
outline, skeleton, overview, get-code-context, find-references,
find-callers, find-callees, deps and changed-symbols exit 4 with one
RebuildRequiredError line and empty stdout, and search refuses the same
way. list-projects, lookup-project, index-status and doctor still
answer, because they report on the index itself and need no rows. Reaching
that verdict needs no service: the version keys are compared against
configuration alone, so index-status prints
fingerprint=needs-reindex reason=... without a probe. A project whose other
keys all match reports fingerprint=unverified reason=embedding-dimension-not-compared instead -- "cannot verify" is its
own value, never folded into a match.
How indexing / staleness works
First index (
add-project, CLI and MCP alike) runs in the foreground: the call returns when indexing finishes. If it is interrupted, the project stays registered but reportsstate=never-indexed(files=0 chunks=0 last_indexed=never);reindex-projectbuilds it.Staleness is reported, never repaired by a read. A read answers from the index as of
meta.last_indexed, compares the indexed files with the tree (stat identity --size,mtime_ns,inode; content is hashed only for files whose stat changed), and reportsfresh,stale(with reasons, capped at five) orunknown(path absent, no completed pass, or the scan exceeded its 5 s / 200,000-entry budget). JSON answers carrystale,stale_known,stale_reasons,stale_reason_count,withheld_count,withheld_files,withheld_summary,withheld_unexamined_count,index_revisionandlast_indexed; a withheld file is counted beside the verdict, never as a stale reason. Text mode prints exactly one stderr line:Warning: index is stale: 3 modified files, 1 deleted file -- <path>; answers describe the index, not the tree; refresh with code-indexer reindex-project <path>A fresh answer prints nothing extra; an unknown verdict prints one line saying the check did not run.
Repair is explicit.
--refreshis the only flag that turns a read into a write: it takes the per-project flock, runs one incremental pass and answers from the result. A held lock isLockedError: indexing in progresswith exit 5 and no answer.--skip-stale-checkis accepted by every command and is inert (the default is to report without repairing);--freshstill means "read the live file" onget-code-contextand is inert elsewhere. The watcher and the three pass commands remain the other writers.Exit codes:
0success (including zero hits -- "no results" is an answer),1other runtime failure,2usage/argument error,3backend or extension unavailable,4the index requires a rebuild,5lock or concurrency conflict. A failed query printsErrorType: messageon stderr with stdout empty; an empty answer printsno resultson stdout and exits 0, so the two are never confused. The full taxonomy and the remedy per type is failures.md.Query cost is bounded: a search resolves ONE project by default (the containing project inferred from the invocation path), fans out only with
--all-projects, makes one embedding attempt with a short timeout, and stops a fan-out at a 30 s wall (skippedwithreason=budget,partial: true).Incremental diff: files are classified by content hash (sha256, not mtime -- branch switches re-index correctly). Only chunks whose hash changed are re-embedded; point IDs are deterministic uuid5, so upserts are idempotent; deleted files are purged.
Chunking: ~1000-char cap (
CHUNK_MAX_CHARS); tree-sitter AST units, regex-window fallback. The embedded text carries a contextual header (embed_text.py, formatcontextual-header-v1).Fingerprint: the manifest records
embed_model,embed_dim,embed_text_version,chunker_version,extraction_version. Any mismatch ⇒needs-reindex(see table above).--skip-stale-checkdoes not bypass this gate.Filtering:
.gitignore/.codeindexignore(nested),--includescope globs, secret-bearing file skips (filename globs + high-confidence content patterns;--allow-sensitiveper-project override), files > 1 MB (MAX_FILE_BYTES), binaries; pure-data chunks are down-weighted in ranking.Concurrency: per-project
flock+ WAL SQLite; two processes indexing one project serialize into exactly one pass ("indexing in progress").
Schema history
Version | What changed | Migration |
v3 |
| automatic ALTER; old rows NULL until |
v4 | index fingerprint + stat fast-path columns on | automatic ALTER; fingerprint backfills on next pass |
v5 |
| automatic ALTER; overview/graph data populate on next reindex |
v6 | ONE reference store: | automatic: |
v7 | line-free symbol identity: | automatic: the old-key symbols table is re-created empty (its rows cannot be re-keyed), the other columns/tables are created; the extraction-version bump marks every index |
-- | FTS5 lexical table ( | automatic backfill on next pass |
Current schema version: 7 (auto-migrates on open; reindex-project
backfills derived columns eagerly).
Configuration
Resolution order: CLI flags > environment variables > defaults. The full
table -- every variable, its default and what it governs -- is in
indexing.md §Configuration.
Note: OLLAMA_URL/QDRANT_URL defaults are LAN placeholders and must be set.
Platform support
Linux (inotify via watchdog) is the supported platform. Watcher degradation
to quiet-period polling happens on inotify exhaustion; Windows is unsupported
(the locking uses fcntl). The index itself is pure SQLite/Qdrant and is
platform-neutral; only watch/locking are POSIX-bound.
Troubleshooting
Run code-indexer doctor -- one line per check (ok|warn|fail <name>: <detail>), exit 1 on any fail. Covers runtime versions, Ollama
(reachable/model/dimension), Qdrant (reachable/version/collections/dims),
INDEX_ROOT writability + disk, SQLite integrity, watcher pidfile/locks, and
per-project fingerprint status. Symptom → action:
Searches misbehave / empty results →
doctor, thenindex-status --project <path>(the positional<path>form still works).RebuildRequiredError: index ... does not match the current configuration ...→needs-reindex; owner runsreindex-project.never-indexedafter a killedadd-project→reindex-project.Watcher dead →
code-indexer unwatch --all, then re-runwatch --background.
The cause and remedy for every error type is failures.md.
Security / privacy
Local-only by design (LAN Ollama/Qdrant). Sensitive files (.env*, keys,
credentials*, high-confidence secret content) are skipped by default and the
skip is counted in index-status; --allow-sensitive is a stored per-project
override. .gitignore/.codeindexignore are honored.
Limitations
References are tree-sitter backed (
confidence=ast) for the languages with a query (python/typescript/tsx/javascript/c/cpp/go/csharp) and textual (confidence=heuristic) for the rest;find-referenceslabels every row with the confidence it carries.C/C++/Java visibility is weak by design (everything public).
The language matrix and per-language caveats live in query.md and docs/languages.md.
Performance
Embedding throughput depends on the Ollama host: measured ~1.2 docs/s with
GPU passthrough (8B model, 4096-dim, batch 48) vs ~0.17 docs/s CPU-only.
The first index of a large repo is the slow part; incremental updates
re-embed only changed chunks. Qdrant upserts ~550 pts/s. Baseline numbers are
2026-09 measurements on the owner's LAN host; re-measure with
code-indexer eval (see semantic.md) before
quoting new ones.
MCP client config (Claude Desktop / Hermes / any stdio MCP client)
The server ships in the mcp extra. One command runs the released server
without installing it:
uvx --from "code-indexer[mcp]" code-indexer-mcpConfigure the client to launch it:
{
"mcpServers": {
"code-indexer": {
"command": "uvx",
"args": ["--from", "code-indexer[mcp]", "code-indexer-mcp"],
"env": {
"OLLAMA_URL": "http://192.168.X.X:11434",
"QDRANT_URL": "http://192.168.X.X:6333"
}
}
}
}When installed as a tool (uv tool install -e ".[mcp]"), point command at
code-indexer-mcp directly (no uvx wrapper). stdout is reserved for the
MCP transport -- all log output goes to stderr; never pipe server stdout
into anything that expects log lines. Listing tools does not require Ollama or
Qdrant to be reachable, and with the semantic extra absent the server starts
with the seven tools that need no embedding client.
Development
uv sync --all-extras # dev env (.venv, incl. both extras)
uv run code-indexer-mcp # run the stdio MCP server
uv run code-indexer list-projects # one-shot CLI (no daemon)
uv run pytest -m "not live" # offline suite (CI runs this)
uv run pytest -m live # live-backend tests (needs Ollama/Qdrant up)
uv run python scripts/generate_skill_docs.py # regenerate the roster and command blocks
uv run ruff check src tests scripts # lint gateruff is a dev dependency and typer a core one, so every uv run command
above runs in one environment: the lint gate answers a result instead of a
spawn failure, and the CLI imports without a separate install. uvx ruff check src tests scripts returns the same lint verdict on a machine with no venv.
A bare system interpreter is not a supported runner for either.
Offline tests use fake embedder/store seams (no backends required); live
tests are marked live and deselected by default. Documentation drift is
guarded by tests/test_docs.py: the roster and the generated command blocks
against the registry, the entry document and each reference against their
budgets, the exit codes against ADR-0003 section 5, and the installed skill
copy against the tracked one. Constraints: core pins
tree-sitter==0.26.0 and tree-sitter-language-pack==1.18.0 (older x86-64
CPUs without x86-64-v2; pure/prebuilt wheels). The semantic extra pins
qdrant-client<1.15, whose resolution brings numpy<2 (1.26.4); the mcp
extra pins mcp<2.
Upgrading between versions
Manifests auto-migrate (see Schema history). reindex-project is only
required when index-status reports needs-reindex (fingerprint mismatch).
A watcher left running across an upgrade must be restarted in the order
unwatch → reindex → watch (see indexing.md).
Available Tools
6 toolsadd_projectA
Register an absolute project directory for semantic indexing.
Creates the Qdrant collection and starts a full initial index in the
background (check progress with index_status). Errors if the path does
not exist or is already registered.
Inputs: path (required). Returns: result
index_statusA
Check indexing state for a project: idle | indexing | stale | error, plus last-pass progress. Also triggers the staleness check.
Inputs: path (required). Returns: result
list_projectsA
List registered projects with per-project index summary and staleness.
Inputs: no named parameters. Returns: result
reindex_projectA
Force a full rebuild of a project's index (chunker/model change, suspected corruption).
Inputs: path (required). Returns: result
remove_projectA
Deregister a project and DELETE its Qdrant collection + manifest + registry entry entirely.
Inputs: path (required). Returns: result
semantic_searchA
Semantic code search across indexed projects. THE hot path.
Automatically runs a staleness check first and incrementally re-indexes
changed files, so results are always fresh (within one scan interval).
Args: query (natural language); project (optional path — omit to search
all registered projects); limit; file_filter (optional substring/glob
on file path, e.g. '*.py').
Inputs: query (required), limit, project, file_filter. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: add_project registers, remove_project deregisters, list_projects lists, semantic_search searches, index_status checks status, and reindex_project forces rebuild. No overlapping or ambiguous functions.
All tool names follow a consistent verb_noun pattern (add_project, remove_project, list_projects, semantic_search, index_status, reindex_project) with snake_case throughout.
Six tools perfectly cover the lifecycle of project management and indexing for a code indexer: add, remove, list, search, status, and reindex. No tool is extraneous or missing.
The tool set provides complete CRUD for projects (add, remove, list) plus essential operations for indexing and searching (semantic_search, index_status, reindex_project). This covers all core workflows for a code indexer.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables indexing and semantic search of codebases and documents via MCP, using Ollama embeddings and Qdrant vector store.5Apache 2.0
- AlicenseNot gradedqualityFmaintenanceIndexes codebases into Qdrant for semantic search, enabling AI assistants to find relevant code by meaning without re-exploring the repo.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to perform semantic code search locally, finding code by meaning rather than exact keywords.3MIT
- FlicenseNot gradedqualityDmaintenanceEnables semantic code search over local repositories, providing tools like semantic_search and list_indexed_repos to Claude Code, so users can find relevant code sections via natural language instead of grep.-