Octocode: a Rust MCP server that gives coding agents an AST graph instead of text chunks

The problem Octocode targets: agents that cannot see file relationships

The README states the problem directly: AI assistants are blind to your codebase, unable to search files, understand dependencies, or remember context across sessions. That framing matters because most retrieval setups for code treat source as flat text chunks. A chunk of auth middleware and a chunk of JWT validation look similar to an embedding model, but nothing in that pipeline records that one imports the other, or that a router wires both into a request path. Octocode's claim is that structure is the missing signal, and it builds that structure with tree-sitter rather than with a language model. The audience is narrow and identifiable: people running Claude Desktop, Cursor, Windsurf or another MCP-compatible client who want the agent to answer questions like which files depend on the payment module, and who are willing to install a binary and point a client config at it.

Two graphs, one of them optional

The architecture diagram in the README splits the system in two. The left branch takes current source through tree-sitter into a live symbol graph, and that graph feeds the MCP graphrag tool. The right branch takes indexed code through embeddings and an optional LLM into persisted file enrichment, which overlays onto the same graph. The distinction is load-bearing. The live AST graph extracts file and symbol nodes plus deterministic contains, imports, calls, extends and implements relationships straight from the source on disk, with no index, no embeddings and no LLM. Graph lookup, relationship traversal, path finding and overview all work with graphrag disabled. Enabling indexed GraphRAG adds semantic file matching, generated descriptions and broader file-level architectural relationships. The README is explicit that symbols are never embedded or LLM-generated, so the generated layer stays at file granularity. That is a conservative design choice, and it is the reason the graph half can run offline.

The MCP surface and what each tool returns

The server exposes four tools: semantic_search, view_signatures, graphrag and structural_search. Semantic search handles meaning-based retrieval over code. View signatures returns structure without reading whole files, which is the cheap way to let an agent decide whether a file is worth opening. The graphrag tool answers relationship questions, and the README's example shows the shape of the output: querying src/middleware/auth.rs returns outgoing imports to jwt.rs and calls to user_store.rs, plus an incoming imports edge from router.rs. Path finding and overview sit alongside traversal. There is also an LSP layer offering go-to-definition, find-references and hover documentation through your language server, which is how the README's call-site example works: process_payment() reported as called from four locations across checkout.rs, refund.rs, billing.rs and a test file. LSP navigation depends on a language server being installed and configured for the language in question, and the README does not enumerate which servers it has been exercised against, so treat that as something to check against your own toolchain.

Getting it running: config keys and commands

The README shows a three-command sequence for the indexed path. First, octocode config --graphrag-enabled true. Then octocode index to build the persisted enrichment. Then octocode graphrag get-relationships --node-id src/middleware/auth.rs to query it. A plain search runs as octocode search "authentication middleware", which the README shows returning src/middleware/auth.rs with a similarity score of 0.9234. Configuration also appears in TOML form as [graphrag].enabled = false, which is the default and the setting that keeps the live graph available while skipping enrichment. The binary is published on crates.io, so cargo install octocode is the expected install path, and the README states Rust 1.95 or later. Local-first operation is the stated default, and the benchmark configuration uses jina-embeddings-v2-base-code through fastembed with no API key. The README does not document a full config file reference, which is a gap if you need to pin model paths or index locations.

What the repository's own benchmark shows

Octocode ships a retrieval benchmark under benchmark/: 127 curated code-search queries with line-range ground truth, run against octocode's own source pinned at commit b1771ba so annotations cannot drift. The published numbers use a fully local stack with jina-embeddings-v2-base-code via fastembed and no reranker, which the README calls a floor rather than a ceiling. Dense vector only and hybrid search with the default RRF weights of 0.7/0.3 produce identical results: Hit@5 0.598, Hit@10 0.717, MRR 0.485, NDCG@10 0.528, Recall@10 0.671. Tilting the fusion toward the keyword signal at 0.3/0.7 lifts those to Hit@5 0.732, Hit@10 0.835, MRR 0.572, NDCG@10 0.620 and Recall@10 0.807. The README attributes the gain to BM25 carrying disproportionate weight for code's exact identifiers. Read that table carefully: it is evidence that the default weighting is misconfigured for code search, not just that tuning helps. The same document notes that a generic local cross-encoder reranker, bge-reranker-base, does not help in this setup. The benchmark covers one repository, so the tuned weights are a starting hypothesis for yours, not a proven default.

Where Octocode is the wrong tool

The semantic half assumes you can run a local embedding model. If your environment forbids downloading model weights, or your repository is small enough that grep and your editor's symbol search already answer the question, the indexing step is pure overhead. The graph half has a different failure mode: it is only as good as tree-sitter's grammar coverage for your language mix. A repository dominated by a language without a maintained tree-sitter grammar will produce a thin graph, and the traversal answers will be correspondingly thin. Nothing in the supplied material lists which languages are supported, so that is unverifiable from the README alone. There is a third constraint worth naming. Because symbols are never embedded or described by an LLM, semantic discovery operates at file granularity. If your question is about a specific function inside a large file, the semantic layer will not isolate it; you are relying on signatures, LSP or the AST graph instead. That is a deliberate trade of recall granularity for determinism, but it is a real ceiling.

How it differs from a general code search tool

Compare Octocode with a conventional vector store over code, the kind you assemble from an embedding model and a chunking script. Both can answer where authentication is handled. The difference appears on the second question. A vector store re-ranks chunks by similarity and has no representation of the fact that auth_middleware.rs imports jwt.rs and is wired into router.rs, which the README calls out as the limitation of treating code as flat text. Octocode answers that from the AST graph without an LLM in the loop. The other comparison the README draws is against documentation lookup tools: those give an agent the manual for the libraries you depend on, while Octocode describes how you assembled them. Those are complementary rather than competing, and a setup using both is coherent. The nearest functional overlap is with language-server-backed navigation, which Octocode also wraps. If your editor already gives you find-references, Octocode's contribution is putting that same capability behind an MCP tool call so the agent can use it mid-conversation.

Maintenance, licensing and what to check before adopting

The project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, but it is not legal advice and you should confirm obligations around notices and modified files with your own counsel if you redistribute. On cadence, the release history shows 0.23.1, 0.24.0 and 0.25.0 within roughly a week in early September 2026, and the version number is still below 1.0. A rapid pre-1.0 cadence means config keys and CLI flags can move between releases, so pin a version rather than tracking latest if you wire this into a team workflow. The persisted index is the other ongoing cost: every index run re-embeds changed files, and the README does not state a storage bound or an incremental-update guarantee, so measure index size and rebuild time on a representative repository before rolling it out. Verify language coverage against your actual file extensions, confirm which language servers the LSP features need, and re-run the benchmark's keyword-tuned weights against your own queries rather than assuming the 0.3/0.7 split transfers.

Editorial conclusion

Adopt Octocode if your agent already speaks MCP and your pain is cross-file questions about imports, call sites and dependencies, since the graph layer works with graphrag disabled and needs no embeddings or LLM calls. Skip it if you only want better fuzzy text matching over a small repository, or if you cannot run a local embedding model for the semantic half. Before committing, verify three things on your own tree: which languages tree-sitter parses in your mix, whether the retrieval benchmark's keyword-tuned RRF weights transfer to your codebase, and how large the persisted index grows for your repository, because the README describes the storage as local but does not state a size bound.

Official sources

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