Codebase MCP Bridge

A compact Model Context Protocol server that gives LLM clients (ChatGPT, Claude, Codex, Cursor, Antigravity) controlled access to a source repository: search, read, patch with rollback, Git, and allowlisted validation.

Design rule: the bridge provides capabilities and facts; the model provides workflow and reasoning.

There are no prompts, no workflow macros and no mandatory call sequence, just 16 small tools with hard limits and a server-side security model the model can't talk its way around.

Highlights

• Safe edits. code.patch applies unified diffs with stale-content checks and takes a rollback snapshot. Every mutation can be undone with code.rollback, which itself creates an inverse snapshot.

• Batched, bounded I/O. Up to 10 searches or 10 file/range reads per call, run with bounded concurrency. Each search returns up to 200 matches by default (500 on request). Combined output is capped and truncation is always reported. File discovery is paginated.

• Secrets stay out. Search and read skip secret-bearing files. Git operations refuse .env, private keys and Git internals. The optional audit log (BRIDGE_ENABLE_AUDIT) stores metadata only, never source or full arguments.

• Operator-controlled trust. The model can list and target workspaces but can't add them. Trust is granted out of band with a CLI.

• Validation without a shell. validation.run runs allowlisted command ids. Its arguments reject shell metacharacters, and output defaults to failures only. Arbitrary shell (command.run) is off unless the operator enables it.

• Two transports. stdio for local agents; Streamable HTTP with OAuth (dynamic client registration, refresh tokens) for ChatGPT connectors and remote clients. High-risk tools stay blocked over HTTP unless explicitly allowed.

Related MCP server: MCP ToolHub

Tools

Typical small fix: code.search → code.read → code.patch → validation.run.

Quick start

npm install
npm run build
node dist/stdio.js          # stdio, for local agents
npm run dev                 # HTTP endpoint at http://localhost:3030/mcp

Client setup (Claude, Codex, Cursor, Antigravity, ChatGPT connector over OAuth) is in docs/clients.md. The full tool reference is in docs/reference.md, and tool-selection guidance for models in docs/mcp-instructions.md.

Configuration

All settings, including limits, ripgrep and diagnostics, are listed in .env.example. Trust another repository: npm run workspace -- trust "C:\path\to\repo" my-repo.

Transient data (symbol cache, rollback snapshots, audit log, OAuth state) lives in .ai-bridge/ inside each repository.

Project layout

src/
  createBridgeServer.ts   tool registration, input schemas and limits
  server.ts / stdio.ts    HTTP (Express + OAuth) and stdio entry points
  workspace-cli.ts        operator CLI for trusted workspaces
  config/                 path allowlist, validation commands, workspace manifest
  services/               repo (search/read), indexer (symbols), patches (diff + rollback),
                          git, policy + security (risk and secret rules), oauth, audit, workspaces
tests/                    node:test suites: tool bounds, security, OAuth, patching, git, routing, performance

Development

npm run typecheck
npm test          # typecheck + node:test suites
npm run build
npm run lint:scripts   # PowerShell syntax check (Windows)

License

MIT. See LICENSE.