codebase-mcp-bridge MCP server
Commit Nov 13, 2026Provides LLM clients with controlled repository access including batched search, rollback-safe code patching, Git operations, and allowlisted validation.
Also known as BTawaifi/codebase-mcp-bridge
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is codebase-mcp-bridge MCP?
codebase-mcp-bridge provides LLM clients with controlled repository access including batched search, rollback-safe code patching, Git operations, and allowlisted validation.
Summary generated from the project's README
About codebase-mcp-bridge MCP server
Giving LLM clients controlled access to source repositories is what codebase-mcp-bridge enables for developers using Claude, Cursor, or ChatGPT. It provides a secure layer between an AI and your code, offering sixteen specialized tools for searching, reading, and editing files without exposing sensitive secrets like .env files or private keys. The server operates via stdio for local agents or through a Streamable HTTP transport using OAuth for remote connections.
Safety is built into the core workflow through features like code.patch, which uses unified diffs and stale-content checks to apply changes. Every mutation is backed by a snapshot, allowing you to undo mistakes using the code.rollback tool. The system manages heavy workloads by batching up to ten searches or file reads per call and uses bounded concurrency to maintain performance. Developers can also perform Git operations or run allowlisted commands through validation.run, while high-risk actions like git.push remain restricted over HTTP unless explicitly configured.
What you can do with it
- 1Reverting accidental code changesA developer can undo a faulty code modification by triggering a rollback of the previous snapshot.
- 2Searching large codebases efficientlyAn AI client can perform batched text or regex searches to find specific patterns across a repository.
- 3Executing safe validation checksYou can instruct an AI to run specific, pre-approved commands to validate code changes without allowing arbitrary shell access.
- 4Managing repository state via GitDevelopers can use the bridge to check status, view diffs, and commit specific file paths.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebtawaifi/codebase-mcp-bridge is public and reachablegithub.com/btawaifi/codebase-mcp-bridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/btawaifi/codebase-mcp-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodebase 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.patchapplies unified diffs with stale-content checks and takes a rollback snapshot. Every mutation can be undone withcode.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.runruns 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.
codebase-mcp-bridge MCP questions
How does the server handle code edits and mistakes?
The server uses a rollback-safe patching system. Every mutation can be undone with code.rollback, which creates an inverse snapshot.
Can the model access sensitive files like .env or private keys?
No, the server includes security rules that skip secret-bearing files and refuse Git operations on .env, private keys, and Git internals.
What transport methods are supported?
It supports stdio for local agents and Streamable HTTP with OAuth for remote clients and ChatGPT connectors.
How is command execution secured?
The validation.run tool only executes allowlisted command IDs and rejects shell metacharacters. Arbitrary shell access via command.run must be explicitly enabled.