Hebros MCP

An MCP server that gives coding agents a map of your codebase.

To find its way around a project, an agent usually lists folders, searches for text, and reads whole files. Every one of those steps costs tokens. Hebros reads your code once and then answers directly: where something is defined, what a file imports, who calls a function.

TypeScript and TSX. Nothing to configure, nothing running in the background. The index is one JSON file in ~/.cache/hebros, kept up to date from git as you edit.

Setup

Needs Node 22 or newer. Any MCP client works — point it at the hebros binary.

Opencode

In opencode.json:

{
  "mcp": {
    "hebros": {
      "type": "local",
      "command": ["npx", "-y", "hebros-mcp", "--root", "/path/to/repo"],
      "enabled": true
    }
  }
}

Claude Code

claude mcp add hebros -- npx -y hebros-mcp --root /path/to/repo

The first hebros names the server locally, so its tools appear as mcp__hebros__get_map. The second is the npm package.

Codex

In ~/.codex/config.toml:

[mcp_servers.hebros]
command = "npx"
args = ["-y", "hebros-mcp", "--root", "/path/to/repo"]

--root is optional. Without it, Hebros indexes the folder you run it in, or whatever HEBROS_ROOT points at.

What the agent gets

Tool	Answers
`get_map`	What's in this file or folder? Every name with its line number, no code bodies. For a file, also what it imports and what imports it.
`find_symbol`	Where is `X` defined? An exact file and line.
`get_deps`	What does this file or package use, and what uses it?
`get_references`	Where is `X` used? Every call site, grouped by file.
`reindex`	Force a refresh. You rarely need it — the other tools stay current on their own.

For example, asking find_symbol("buildEdges") gets back:

src/imports.ts:427-445 + function buildEdges: export function buildEdges(...)

One line, instead of hunting through folders and opening three files.

Every answer stays under about 6 KB. When there's too much to fit, you get a short summary saying where to look next, rather than a list that quietly stops halfway.

The first question builds the index, which takes well under a second for a few hundred files. After that Hebros asks git what changed and re-reads only those files, so answers come back in milliseconds.

It uses fewer tokens

Every file an agent opens fills up the space it has to think in. A map of a file is much smaller than the file.

Here is what that looks like on a real project of 324 files:

To answer	Without Hebros	With Hebros
What's in this file?	read it — 4.5 KB	a map of it — 1.4 KB	3x smaller
Where is `useAppStore`?	search — 8 KB of matches to read	one line — 217 B	37x smaller
What's in this project?	a list of files — 13 KB	a map — 365 B	36x smaller

Across 230 files, that is roughly 260,000 tokens of reading turned into 52,000.

How much you save depends on what you ask. A name used in 40 places is where it helps most, because searching for it hands back 40 lines to read. A name used once saves only about half. And on a small project — say 20 files — the map is no smaller than a plain file list. What you get there is a precise answer rather than a shorter one.

Good for local models

This helps most when there isn't much room. A model running on your own machine usually has space for 8,000 to 32,000 tokens, so one or two large files can use it all up. The model also has to read the whole prompt before it says anything, so a shorter prompt means a faster first word.

Hebros does the reading up front, on the CPU, and hands over a few hundred bytes of ready-made answer. That leaves the space free for the actual work.

Good to know

TypeScript and TSX only. Other languages need a small adapter.
get_references matches names as text, not by type. For a common name, pass file to narrow it down.
It understands tsconfig paths and workspace packages (pnpm, npm, yarn).
The index is plain JSON. Comfortable up to a few thousand files.

docs/DESIGN.md — how the index works and why it's built this way
CONTRIBUTING.md — local setup and ground rules

License

MIT — see LICENSE.

hebros-mcp