Octocode: a Rust MCP server that gives AI agents a structural map of your code

The gap Octocode targets: AI assistants read files, they do not read structure

An assistant with filesystem access can open src/middleware/auth.rs and read it. What it cannot do from that file alone is tell you that auth.rs imports jwt.rs for token validation, calls user_store.rs for lookup, and is wired into the request pipeline by router.rs. The README states the problem plainly: AI assistants are blind to your codebase, they cannot search files, understand dependencies, or remember context across sessions. Octocode's answer is to materialize the dependency structure as a graph and expose it over the Model Context Protocol, so the assistant queries relationships instead of guessing them from adjacent files.

The intended user is not someone browsing a repository. It is someone who has already wired Claude Desktop, Cursor, Windsurf or another MCP-compatible client into their editor and now wants that client to answer questions like "what files depend on the payment module". The README's own examples are exactly that shape: a question about where authentication is handled, a question about reverse dependencies, a question about call sites. All three are cross-file questions, and all three are the kind of thing flat text chunking handles badly.

Two graphs, not one: the live AST graph and the optional indexed layer

The architecture diagram in the README splits the system into two paths that meet at the MCP graphrag tool. On the left, current source goes through tree-sitter AST parsing into a live symbol graph. That graph carries file and symbol nodes plus deterministic relationships: contains, imports, calls, extends and implements. The README is explicit that this path needs no index, no embeddings and no LLM, and that graph lookup, relationship traversal, path finding and overview all work with [graphrag].enabled = false. If you only want the structural layer, you can have it without paying for an embedding model.

On the right, indexed code goes through embeddings and an optional LLM into persisted file enrichment. Enabling indexed GraphRAG overlays semantic file matches, LLM descriptions and broader file-level architectural relationships on top of the live graph. One design decision is worth calling out: the README states that symbols are never embedded or LLM-generated. Only files get that treatment. That keeps the symbol layer deterministic and cheap to rebuild, and it means a stale description can never contaminate a go-to-definition answer.

Search is a separate pipeline. The README describes hybrid retrieval combining semantic similarity, BM25 full-text search and reranking, exposed through the semantic_search MCP tool alongside view_signatures, graphrag and structural_search. LSP integration is a fourth source of precision: go-to-definition, find-references and hover documentation come from your language server, not from the index.

Installing Octocode and running a first index

The repository ships an install.sh at the top level and an INSTALL.md, and the Dockerfile downloads a pre-built static binary from GitHub Releases rather than compiling. The Dockerfile maps Docker's TARGETARCH to release assets named with the musl target triples, so on amd64 it fetches octocode-${OCTOCODE_VERSION}-x86_64-unknown-linux-musl.tar.gz and on arm64 the aarch64 equivalent. If you build the image yourself, the version is a build argument.

docker build --build-arg OCTOCODE_VERSION=0.14.0 .

The README's Quick Start section is the reference for the CLI path, and the version in that build argument is the one the Dockerfile comment uses as its example, not the current release. For a source build, Cargo.toml sets rust-version = 1.95, so check your toolchain before starting. The project publishes to crates.io under the name octocode.

The first real workflow the README demonstrates turns on the persisted graph and then queries it. Note that these are three separate commands: the config change, the index build, and the relationship query.

octocode config --graphrag-enabled true
octocode index
octocode graphrag get-relationships --node-id src/middleware/auth.rs

What you should see is a two-part listing. Outgoing edges show imports pointing at jwt (src/auth/jwt.rs) with the note "token validation logic", and calls pointing at user_store (src/db/user_store.rs) with "user lookup by token". Incoming edges show router (src/router.rs) importing the file to wire auth into the request pipeline. The descriptions attached to those edges are the LLM enrichment layer, so they only appear when indexed GraphRAG is enabled; with [graphrag].enabled = false you get the structural edges without the prose.

Semantic search is a single command and reports a similarity score rather than a graph traversal.

octocode search "authentication middleware"

The README's example output is a single hit, src/middleware/auth.rs, with a similarity of 0.9234. If your first query returns nothing useful, the benchmark section below explains why the default fusion weights may be the cause.

The retrieval benchmark is the most useful thing in the repository, and it argues against the default

Octocode ships a reproducible retrieval benchmark in benchmark/, described as 127 curated code-search queries with line-range ground truth, run against octocode's own source pinned at commit b1771ba so the annotations do not drift. The published numbers use a fully local, no-API-key stack: jina-embeddings-v2-base-code via fastembed, and no reranker. The README calls that a floor rather than a ceiling, which is a fair reading, since adding a reranker or a hosted embedding model could only be compared against it.

The result worth your attention is that dense vector search alone and hybrid search with the default RRF weights of 0.7/0.3 produce identical figures: Hit@5 of 0.598, Hit@10 of 0.717, MRR of 0.485, NDCG@10 of 0.528, Recall@10 of 0.671. Tilting the fusion toward the keyword signal at 0.3/0.7 changes every one of those: Hit@5 rises to 0.732, Hit@10 to 0.835, MRR to 0.572, NDCG@10 to 0.620, Recall@10 to 0.807. The README's own explanation is that BM25 carries disproportionate weight for code's exact identifiers, and it reports the lift as +22% Hit@5 and +20% Recall@10 at zero added cost.

Read that carefully. The default configuration of a hybrid search system performs the same as not having the keyword half at all, on the project's own benchmark. The benchmark also flags what does not help: a generic local cross-encoder reranker, bge-reranker-base, is listed among the things that did not improve results. That is a specific, falsifiable claim published alongside the harness that produced it, which is more than most code-search projects offer. It is also a signal that the defaults were not tuned on this workload, and that you should expect to change them.

Where Octocode is the wrong tool

The live graph is only as good as tree-sitter's coverage of your language. The README's relationship vocabulary is imports, calls, extends and implements, which maps cleanly onto languages with those constructs. If your codebase is mostly a language where the meaningful relationships are dynamic, resolved at runtime, or expressed through configuration rather than syntax, the graph will show you a thinner picture than the marketing implies, and the MCP graphrag tool will answer confidently from an incomplete edge set.

The second boundary is scope. This is a local-first tool that indexes your working tree. Nothing in the README describes a shared index, a hosted service, or a way for a team to query one canonical graph. If your requirement is a central code search that spans many repositories and stays consistent for everyone, Octocode's model of each developer indexing locally is a mismatch, not a smaller version of the thing you want.

The third is the enrichment layer's cost. The README marks LLM descriptions as optional, which is honest, but it also means the feature that makes graphrag output readable is the one that introduces an external dependency and a per-file generation cost. With enrichment off you get deterministic edges and no prose. With it on you get descriptions you have to keep fresh as files change. The README does not document how enrichment is invalidated when a file is edited, so treat incremental freshness as something to verify rather than assume.

How it differs from a documentation MCP server

The closest alternative in the same MCP ecosystem is a documentation lookup server, the kind that indexes library docs and API specs so an assistant can quote the correct signature for a framework. The README draws the line itself: doc tools give AI the manual for libraries you use, Octocode gives AI the blueprint of how you put them together. That is not a marketing distinction. A docs server answers "what arguments does this library function take". Octocode answers "which of my files call it, and what imports the file that does". The indexes are disjoint: one is external and versioned by upstream, the other is internal and versioned by your commits.

Against standard RAG over code, the difference is the unit of retrieval. Text-chunk RAG retrieves a passage because it looks similar to the query. Octocode's graph layer retrieves a node because a deterministic edge connects it to something you named. The README's comparison table puts cross-file navigation and relationship types as the dividing line, and the benchmark numbers support the claim that similarity alone is not enough for code: 0.598 Hit@5 for dense-only retrieval on 127 curated queries is a real ceiling. The practical consequence is that the two approaches fail differently. RAG fails by returning a plausible but unrelated snippet. Graph traversal fails by returning nothing when the edge does not exist, which is easier to notice and easier to correct.

Licence, releases and what upgrades cost you

Octocode is Apache-2.0, stated in both the README badge and the Cargo.toml license field, with the author listed as Muvon Un Limited. Apache-2.0 includes an explicit patent grant and requires you to preserve notices and state changes; it is permissive enough for commercial use. If you redistribute a modified binary, the licence text and attribution obligations travel with it. That is the extent of what the repository supports saying here, and it is not legal advice.

The release cadence is fast. Three releases are listed in the first week of September 2026: 0.25.0 on 2026-09-05, 0.24.0 on 2026-09-02 and 0.23.1 on 2026-08-31, with Cargo.toml already at 0.26.0. The last push to master was on 2026-09-07. That pace is relevant to your upgrade budget in a concrete way: the Dockerfile pins an explicit OCTOCODE_VERSION build argument, so a container build is reproducible only as long as you keep that pin. A pre-1.0 project moving this quickly can change configuration keys between minor versions, and the README documents the config surface as TOML under [graphrag]. Check CHANGELOG.md before bumping, and keep your pinned version in the Dockerfile rather than tracking latest.

Editorial conclusion

Adopt Octocode if you already drive an MCP-capable assistant and you want it to answer dependency questions from your working tree rather than from pasted snippets. Skip it if your language has no tree-sitter grammar in the build, or if you need a hosted index shared across a team, since the README describes a local-first binary and an optional LLM enrichment step you would have to configure yourself. Before committing, run octocode index on your largest crate and check the graphrag output for your own entry points, then confirm the benchmark's keyword-tuned RRF weights (0.3/0.7) improve retrieval on your queries, because the default 0.7/0.3 configuration scores identically to dense-only search in the project's own results.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Muvon/octocode on GitHub
3. Project website
4. README
5. Releases