repocontext

The only MCP server you need for context-efficient codebase learning. 11 read-only tools, tree-sitter parsing, zero LSP overhead. Saves 90%+ tokens vs naive file reading and minimizes the number of tool calls needed to learn a repo.

Quick start

npx -y @idea404/repocontext start

Add to opencode config:

{
  "mcpServers": {
    "repocontext": {
      "type": "local",
      "command": ["npx", "-y", "@idea404/repocontext", "start"],
      "enabled": true
    }
  }
}

Token budget

Measured on the repocontext repo itself (11 source files, ~800-line server.ts):

| Scenario | Naive | repocontext | Saved | |---|---|---|---| | Read file structure | 5,986 tok | 500 tok | 92% | | Find symbol across 10 files | 15,653 tok | 18 tok | 100% | | Project overview (34 files) | 53,704 tok | 36 tok | 100% |

Naive = cat/grep on matching files. Tokens estimated at 4 chars/token.

Tools (11 total)

| Tool | Use it when you want to... | |---|---| | repo_overview | Learn a repo in one call: purpose, stack, languages, entry points, config, structure | | find | Search files, symbols, or code content in one tool | | read | Read line ranges, symbol bodies, or structural outlines | | query | Ask a natural-language question and get relevant files + symbols | | trace | Trace a symbol: definition, references, recent commits, blame | | deps | See external dependencies and internal import graph | | tests | Find tests for a file or overall test coverage | | changes | See recent commits, authors, and hot files | | docs | Search README/markdown and code comments for a topic | | analyze | Deep-dive a file: symbols, imports, exports, refs, optional blame | | roots | Show allowed filesystem roots |

All read-only, bounded, and root-safe.

Learning workflow

1. Start with repo_overview to get the big picture.
2. Ask query for specific mechanisms ("how does auth work?").
3. Use find + read to drill into files.
4. Use trace to follow a symbol across the codebase.
5. Use deps, tests, and changes for cross-cutting context.

Why tree-sitter

Every tool returns only structural metadata — symbol names, line ranges, import sources — and avoids sending whole files unless requested. No LSP, no type checker, no semantic resolution.

Supported languages

WASM-based tree-sitter grammars: TypeScript/TSX, JavaScript, Python, Go, Rust, Java, C/C++, C#, Bash, Ruby, Swift, Kotlin, Elixir, Scala, PHP, OCaml, CSS, HTML, JSON, Lua, Dart, Zig, YAML, TOML, Vue, Elm, Objective-C.

Runs on any OS that supports Node.js, including NixOS, without native C++ compilation.

Development

npm install
npm run build
npm test

License

MIT