# scalpel

Symbol-level codebase retrieval MCP server. Give an agent `get_symbol(name)` instead of a whole file — it returns just the definition and its usages.

## Why

Reading whole files to answer one question about one symbol wastes context. scalpel avoids the read entirely instead of compressing it after the fact.

## Setup

```bash
npm install && npm run build

# index a repo (lang: ts | python | go, default ts)
node dist/build-index.js /path/to/repo /path/to/repo/.scalpel/index.db [lang]

# run the MCP server over stdio
node dist/server.js /path/to/repo /path/to/repo/.scalpel/index.db
```

Point an MCP client at it (stdio transport, args: `<repoPath> <dbPath>`).

## Does it actually help?

- **Token cost:** ~96% fewer tokens than reading whole files, across 4 repos and 3 languages, holds up under formal significance testing.
- **Real dollar cost:** same story once billing/caching is accounted for, flat across weak/mid/strong model tiers.
- **Does it fix bugs faster?** No net advantage. Tested on 57 real historical bugs — an agent with scalpel's tools and a plain grep/Read agent fix the same bugs, at basically the same speed. This is the paper's headline finding, not a footnote.

Full numbers, every caveat, every negative result: **[RESULTS.md](RESULTS.md)**.