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.

Tools

Group	Tools	Notes
Workspace	workspace.list, workspace.status	workspaceId is optional; defaults to the repo the server started in
Code	code.search, code.read, code.symbols, code.references	Text/regex search and file globbing; incremental lexical symbol cache. code.references is explicitly low-confidence lexical, not an LSP graph.
Edits	code.patch, code.write, code.delete, code.rollback	All mutations snapshot for rollback
Git	git.status, git.diff, git.commit, git.push	git.commit can stage and commit only given paths. An invalid diff base fails instead of silently picking another. git.push is treated as high risk.
Validation	validation.run, command.run	Allowlisted checks; command.run is an opt-in, time- and output-bounded escape hatch

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

Variable	Default	Meaning
BRIDGE_REPO_ROOT	launch directory	Repository the bridge serves when no workspaceId is given
BRIDGE_PORT	3030	HTTP port
BRIDGE_PUBLIC_URL	http://localhost:<port>	OAuth/public issuer URL (set to your tunnel URL)
BRIDGE_ALLOW_UNAUTHENTICATED_LOCAL	false	Skip OAuth for local HTTP; does not unlock high-risk tools
BRIDGE_REQUIRE_CLIENT_SECRET	true	Require an OAuth client secret
BRIDGE_SECURITY_STRICT	false	Refuse to start when security warnings exist
BRIDGE_OAUTH_SETUP_SECRET	unset	Protect dynamic client registration
BRIDGE_ALLOW_HIGH_RISK_HTTP	false	Allow git.push / command.run over HTTP
BRIDGE_ENABLE_COMMAND_RUN	false	Enable command.run
BRIDGE_MAX_COMMAND_OUTPUT_BYTES	50000	Raw command output cap
CODEBASE_MCP_WORKSPACE_MANIFEST	unset	Override the validation-command manifest

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.