# codebase-bridge-mcp

A read-only [MCP](https://modelcontextprotocol.io) server that lets a Claude chat — in
the desktop or web app — explore your local repository and answer questions about it,
returning synthesized answers with `file:line` references. **No copy-pasting files, no
giving the chat write access to your machine.**

`ask_codebase` runs headless Claude Code (`claude -p`) inside your repo with an
**exclusive** read-only tool set (`Read Grep Glob` — no Edit, Write, Bash, agents, or
MCP) and a hook that **confines reads to the target repo**, so a disposable agent
explores the code and returns a synthesized, `file:line` answer. See
[Security](#security) for exactly what is and isn't enforced.

```
Claude client  --MCP-->  codebase-bridge  -->  claude -p (Read/Grep/Glob only)
                                                └─ explores /path/to/your/repo
```

## Why I built this

I do my best thinking about a problem in a conversational Claude chat, not in a coding
agent — the back-and-forth on an idea tends to go deeper there. But every time I wanted
to ask about a specific part of my code, I had to go hunting for the right file, find
the relevant section, and paste it in by hand — every single question. It broke the
flow exactly when I wanted to think freely.

I went looking for something to close the gap and found the existing codebase tools all
point the wrong way: filesystem and repo-packing servers (like Repomix) feed a coding
agent that already has your repo, and structural-index servers (like
codebase-memory-mcp) need a coding agent to be the brain. Nothing brought a finished,
read-only answer about my code into the chat where I was actually thinking. So I built
it: it shells out to a headless, read-only Claude scoped to a single repo (Read/Grep/Glob
only — no Write, no Bash), and hands the synthesized answer back to my chat. I can
interrogate my codebase mid-conversation without ever leaving the thinking.

## Requirements

- [Claude Code](https://claude.com/claude-code) (`claude`) installed and authenticated.
- [`uv`](https://docs.astral.sh/uv/) (runs the server with zero install — deps are
  declared inline in `server.py`).
- For the optional `http` transport: [`cloudflared`](https://github.com/cloudflare/cloudflared)
  or any HTTPS tunnel.

## Tools

| Tool | What it does |
| ---- | ------------ |
| `ask_codebase(question, thread="", model="", effort="", show_steps=False)` | Explore the repo read-only and answer. |
| `bridge_cost()` | Return the per-thread + grand-total cost ledger for this server process. |
| `bridge_forget(thread="")` | Drop a thread's session (or all threads) so the next call starts fresh. |

`ask_codebase` parameters:

- **`thread`** — a friendly name (e.g. `"auth-investigation"`). Reuse the **same name**
  to keep one Claude Code session alive — **turn-based steering**: each follow-up keeps
  prior context, so you redirect it and it stays cheap (prompt-cache hits, measured
  45% → 95% → 99% cache-read across turns). Omit for a one-off fresh session.
- **`model`** — e.g. `"sonnet"` / `"opus"`. **Binds** to a thread on its first call; a
  *different* model on an existing thread is **refused with a note**, because switching
  models forces a full-context reprocess. Start a new thread for a different model.
- **`effort`** — reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`. Per-call
  (safe to vary within a thread — unlike `model` it doesn't invalidate the cache).
  Lower = cheaper/faster; raise it for hard cross-file reasoning. Unknown values are
  ignored with a note.
- **`show_steps`** — append the exploration trail so you see *how* it reached the
  answer and can steer the next turn.

Example answer:

```
Auth is enforced in app/middleware.py:42 (verify_token), called from the
@requires_auth decorator in app/security.py:18.

[bridge] explored via 2 step(s):
  1. grep 'verify_token'
  2. read app/middleware.py
--
[bridge] model=opus-4-8 | call=$0.0383 | cache 58k read / 19 fresh (100% cached)
[bridge] thread 'auth' total=$0.81 over 3 call(s) -- reuse this thread for cheap follow-ups
```

## Install / run

### stdio (recommended — Claude Desktop & Claude Code)

stdio is launched as a local subprocess by the client: no URL, no tunnel, no token.

**Claude Code:**

```sh
claude mcp add codebase-bridge -- uv run --script /ABS/PATH/server.py --repo /ABS/PATH/your-repo
```

**Claude Desktop:** edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) — see [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json):

```json
{
  "mcpServers": {
    "codebase-bridge": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--script", "/ABS/PATH/server.py", "--repo", "/ABS/PATH/your-repo"]
    }
  }
}
```

Use the **absolute path to `uv`** (`which uv`) — Claude Desktop doesn't inherit your
shell `PATH`. Restart Desktop after editing. Then ask:
*"Use ask_codebase on thread 'auth', show_steps: how does login work?"*

### http (only for claude.ai web)

claude.ai reaches servers from Anthropic's cloud, so it needs a public URL + token:

```sh
export BRIDGE_TOKEN=$(openssl rand -hex 16); echo "token: $BRIDGE_TOKEN"
uv run --script server.py --transport http --repo /ABS/PATH/your-repo   # 127.0.0.1:8765
cloudflared tunnel --url http://localhost:8765                  # new terminal
```

http transport **refuses to start without `BRIDGE_TOKEN`** (pass `--insecure-no-auth`
to deliberately run an open server, e.g. when you front it with your own auth). It
binds **`127.0.0.1`** by default — the tunnel connects to localhost; set `--host
0.0.0.0` only if you really need other interfaces. The token check is constant-time.

Add `https://<tunnel>.trycloudflare.com/mcp` (no trailing slash) as a custom connector
in claude.ai with the bearer token.

## Configuration

All knobs have CLI flags and/or env vars:

| Env | CLI | Default | Meaning |
| --- | --- | ------- | ------- |
| `BRIDGE_REPO` | `--repo` | current dir | repo Claude Code explores |
| `BRIDGE_TRANSPORT` | `--transport` | `stdio` | `stdio` or `http` |
| `BRIDGE_TOKEN` | — | unset | http bearer token (http refuses to start unless set or `--insecure-no-auth`) |
| `BRIDGE_HOST` | `--host` | `127.0.0.1` | http bind address |
| `BRIDGE_PORT` | — | `8765` | http listen port |
| `BRIDGE_TIMEOUT` | — | `240` | per-call wall-clock cap (seconds) |
| `BRIDGE_MODEL` | — | Claude Code default | default model for new threads / ephemeral calls |
| `BRIDGE_MAX_CONCURRENT` | — | `4` | cap on concurrent `claude` subprocesses (DoS/cost guard) |
| `BRIDGE_THREAD_TTL` | — | `1800` | idle seconds before a thread session is dropped (`0` = never) |
| `BRIDGE_MAX_THREADS` | — | `256` | live-thread cap before LRU eviction |
| `BRIDGE_CONFINE_READS` | — | `1` | PreToolUse hook confines reads to `--repo` (`0` = read anywhere) |
| — | `--insecure-no-auth` | off | allow http without a token (explicit opt-in; refused on non-loopback host) |

## Security

This project has **not been independently security-audited.** It is hardened, and the
guarantees below are enforced and were verified empirically — but read this before
exposing it to untrusted input.

**What is enforced (default), at Claude's tool-dispatch layer:**

- **Exclusive read-only tool set.** The agent is launched with `--tools "Read Grep
  Glob"` — the *exclusive* built-in tool flag (unlike `--allowedTools`, which is merely
  additive and lets unlisted tools still run). The agent literally has **no Bash, Edit,
  Write, agent/subagent, or MCP tool** — verified: it reports only `Read/Grep/Glob`.
- **Reads confined to `--repo`.** A `PreToolUse` hook (this script, registered via
  `--settings`) runs host-side before every tool call and **denies any read whose path
  resolves outside the target repo** (absolute paths, `../`, `/proc/self/environ`, etc.)
  — verified: reading `/etc/hosts` is rejected with "outside the target repo". This is
  the one thing no `claude` flag does (Read accepts absolute paths by design). Disable
  with `BRIDGE_CONFINE_READS=0` for trusted local cross-repo use.
- **No shell injection / no flag injection.** Argv list (no shell); the question is
  passed after a `--` end-of-options separator so it can't be reparsed as a flag.
- **The server's own secrets aren't inherited.** `BRIDGE_*` env vars (incl.
  `BRIDGE_TOKEN`) are stripped from the child env, and `/proc/self/environ` is outside
  the repo so the read hook blocks it too.
- **http transport.** Refuses to start without `BRIDGE_TOKEN` (override with
  `--insecure-no-auth`, itself refused on a non-loopback host), binds `127.0.0.1`,
  constant-time token compare, concurrent subprocesses capped (`BRIDGE_MAX_CONCURRENT`).

**The honest caveats:**

- **This is policy enforcement, not a kernel sandbox.** The tool restriction and read
  hook are evaluated by Claude Code host-side and are deterministic (the model can't
  reason around them), but they are not an OS-level boundary. For a **fully untrusted**
  client (e.g. exposed over a public tunnel), additionally wrap the process in an OS
  sandbox (`sandbox-exec` on macOS, `bubblewrap` on Linux, or a container) so even a
  hypothetical `claude`/Node compromise can't escape. (`code.claude.com/docs/sandboxing`.)
- **Files *inside* the repo are readable** — including any secrets committed there
  (`.env`, keys). Point it at repos you trust to expose.
- **Prompt injection.** Untrusted content inside repo files could try to misdirect the
  agent; the read-confinement hook limits the blast radius to the repo itself.

## Known limitations

- **State is in-memory and per-process.** Thread sessions and the cost ledger reset on
  restart; there is no cross-restart persistence (by design for now). Idle threads are
  dropped after `BRIDGE_THREAD_TTL` and evicted by LRU past `BRIDGE_MAX_THREADS`.
- **No mid-flight cancellation.** Cancelling the MCP request does not kill the running
  `claude` subprocess; it finishes (bounded by `BRIDGE_TIMEOUT`).
- **Depends on the `claude` CLI's output schema.** It parses `--output-format
  stream-json`; a future CLI change could require an update (the smoke test guards the
  tool surface, not the parser).
- **Not independently security-audited.** Reviewed adversarially (incl. by separate AI
  reviewers) but not professionally audited.

## Cost model

Each `ask_codebase` call spins up a fresh headless Claude Code agent, so dollar cost
varies with how much it explores. The win from `thread` reuse shows as a climbing
**cache-hit rate** and cheap short follow-ups — not a strictly lower price every call.
State is in-memory per server process; restarting resets threads and the ledger.

## Development

```sh
uv run tests/smoke.py   # MCP handshake + tool-surface check (no API key needed)
uv build                # build wheel + sdist
```

CI runs both on every push/PR (`.github/workflows/ci.yml`).

## License

MIT — see [LICENSE](LICENSE).