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.

Related MCP server: Semantic JS MCP

What the agent gets

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:

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.

More

• 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.