Skip to main content
Glama
MCP RepoBridge
by Zxyy-mo

MCP RepoBridge

A guarded MCP bridge for repository context, Docker-sandboxed commands, document Skills, trusted local MCP servers, and optional Codex handoff.

简体中文

MCP RepoBridge lets ChatGPT and other MCP clients inspect a project workspace without giving them a host shell.

It exposes a small set of read-only repository tools, routes command execution through a fixed Docker sandbox backed by a filtered disposable workspace, and can optionally hand implementation work off to a local Codex worker. It is intentionally smaller than a general agent framework: it is the bridge between an LLM interface and a repository, not a replacement for your development environment.

IMPORTANT

Project status (November 2026) — expected final release. ChatGPT and Codex usage quotas are set to be merged in December 2026. Once they share a single pool, the main reason this bridge exists — letting ChatGPT inspect a repo while Codex quota stays separate — goes away, so the project's practical value under ChatGPT will be limited. The repository stays available as-is; no further updates are planned.

Why This Exists

This project came from a pragmatic workflow:

  • ChatGPT's web UI is good for interactive reading, questioning, and planning.

  • Codex is better suited for longer implementation work.

  • Their usage limits and working modes are separate enough that it is useful to let ChatGPT inspect a repository without spending Codex work on every small question.

  • Exposing a normal local shell to a remote LLM is too much trust.

MCP RepoBridge sits in the middle. ChatGPT can read and search the project via MCP, run bounded checks inside Docker, and, when explicitly enabled, queue tasks for Codex to handle separately.

ChatGPT / MCP client
        |
        | HTTPS + bearer token
        v
MCP RepoBridge
        |
        |-- read-only host workspace file tools
        |
        |-- filtered disposable copy -> Docker sandbox execution
        |
        |-- optional document Skills / trusted host MCP gateway
        |
        |-- optional Codex task queue

The result is a small, auditable MCP server for people who want the convenience of "connect MCP and start working" without handing an LLM direct access to the host machine.

Related MCP server: engineering-mcp

What It Provides

Default MCP tools:

read_file
read_files
list_directory
grep_files
find_files
project_task_list
project_task_run
exec_container
sandbox_status
sandbox_start
sandbox_stop
sandbox_task_status
sandbox_task_tail
sandbox_task_cancel
workspace_bootstrap
workspace_info
audit_log_tail

Optional Codex handoff tools:

codex_task_create
codex_task_list
codex_task_status
codex_task_tail
codex_task_cancel

Optional extension tools:

extension_discover
skill_read
mcp_call              # only when trusted host MCP execution is enabled

What it deliberately does not provide:

run_shell
host_exec
write_file
edit_file
arbitrary_docker

Security Model

MCP RepoBridge assumes the MCP client and the model may make unsafe requests. The runtime enforces boundaries in code rather than relying on prompts.

Key defaults:

  • host shell execution is not exposed

  • host write/edit tools are not exposed

  • file access is restricted to a configured workspace root

  • path traversal and symlink escapes are rejected

  • secret-like paths such as .env, .ssh, .aws, .gcloud, and .secure-mcp are blocked by default

  • command execution goes through docker exec into a fixed container

  • the final container receives a filtered, disposable workspace copy instead of the host workspace; secret-like paths are omitted and writes are discarded

  • the model cannot choose Docker flags, container name, image, or mounts

  • the default sandbox has --network none

  • the default sandbox does not mount host HOME, SSH keys, cloud credentials, or the Docker socket

  • command policy rejects common network, Docker, privilege escalation, and destructive commands

  • HTTP transport enforces Origin and Host allowlists

  • HTTP MCP sessions have a configured cap and idle TTL

  • Codex worker child processes receive an allowlisted, secret-filtered environment

  • extension support and host MCP execution are separate, disabled-by-default gates

  • Skills are treated as untrusted Markdown instructions and are never executed

  • host MCP commands, arguments, working directory, environment mappings, and tool allowlists come only from trusted local configuration

  • an MCP call must use a short-lived discovery ID and matching schema revision

  • host MCP child-process concurrency is capped and wildcard tool access is rejected

  • every tool call is audited

  • every tool result uses a stable status/data/error/next-action envelope

Docker is risk reduction, not perfect isolation. Read SECURITY.md and docs/06-threat-model.md before exposing the runtime through a public tunnel.

Quick Start

Install and build:

npm install
npm test
npm run build

Build the default sandbox image:

docker build -f docker/Dockerfile.sandbox -t secure-mcp-sandbox:latest docker

Start the bridge for a project:

npm run --silent bridge -- start \
  --project-root /absolute/path/to/project \
  --tunnel none

Stop it:

npm run --silent bridge -- stop \
  --project-root /absolute/path/to/project

The bridge writes generated state under:

<project-root>/.secure-mcp/

That directory contains runtime config, bearer tokens, logs, audit records, and optional Codex task state. It is ignored by git and blocked by the file tools.

ChatGPT Setup

For ChatGPT or another remote MCP client, start the HTTP runtime with a tunnel.

Cloudflare Quick Tunnel:

npm run --silent bridge -- start \
  --project-root /absolute/path/to/project \
  --tunnel cloudflare

Managed tunnel or reverse proxy:

npm run --silent bridge -- start \
  --project-root /absolute/path/to/project \
  --tunnel external \
  --public-base-url https://mcp.example.com

The command prints:

publicMcpUrl
token

In ChatGPT, configure:

URL: publicMcpUrl
Authentication: Access token / API key
Header scheme: Bearer
Token: token value only

Do not put Bearer into the token field if the UI already has a Bearer/header scheme option. The HTTP header must end up as:

Authorization: Bearer <token>

For a Linux server deployment flow, see docs/11-linux-server-tunnel.md.

Docker Sandbox

The default sandbox image is intentionally small. It is based on Node and includes:

node
npm
bash
git
ripgrep
ca-certificates
util-linux

It does not try to be a full polyglot development image. If a project needs Python, Go, Rust, or another toolchain, build a trusted image and select it from local configuration:

{
  "sandbox": {
    "image": "secure-mcp-sandbox:latest"
  }
}

The MCP client must not be allowed to choose image names, Docker flags, mount paths, network mode, or container names.

Commands that finish within the configured yield window return inline. Longer commands become durable sandbox_task_* jobs with incremental log reads and cooperative cancellation. project_task_list discovers conventional project tasks without exposing package-script bodies, and project_task_run resolves the selected task server-side before applying the normal command policy.

Optional Skills and Local MCP Servers

The extension gateway is disabled by default. It adds a low-round-trip flow similar to local MCP/Skill aggregators while preserving two separate trust levels:

  • document Skills scan configured directories and return bounded SKILL.md content; no Skill script or runtime is executed

  • local MCP servers start an exact stdio command from trusted configuration on the host, discover its allowlisted tools, then proxy a revision-bound call

Copy examples/extensions.example.json, edit the absolute paths and allowlists, then start with:

npm run --silent bridge -- start \
  --project-root /absolute/path/to/project \
  --tunnel none \
  --extensions-config /absolute/path/to/extensions.json

The example enables document Skills but keeps hostMcpEnabled false. Change it to true only after reviewing every configured executable, argument, tool allowlist, and environment mapping.

The client workflow is:

extension_discover(kind=skill) -> extension_discover(name=...) -> skill_read(revision=...)
extension_discover(kind=mcp)   -> extension_discover(name=...) -> mcp_call(discoveryId, revision, tool, arguments)

The model cannot pass a process command, arguments, cwd, or environment through any MCP tool. Environment values are copied only by locally configured variable name mappings, and audit records store argument names rather than values. Upstream tool metadata and results are explicitly labeled as untrusted content.

Important: an enabled local MCP server is trusted native host code. It runs with the OS privileges of RepoBridge and is outside the Docker sandbox. Tool allowlists and environment filtering reduce exposure to the model; they do not sandbox a malicious MCP executable.

Optional Codex Handoff

Codex handoff is disabled by default.

When enabled, ChatGPT can queue structured tasks through MCP. A separate local or server-side worker claims the tasks and runs Codex in the workspace.

Start the bridge with handoff tools:

npm run --silent bridge -- start \
  --project-root /absolute/path/to/project \
  --tunnel none \
  --codex-handoff true

Run the worker in another terminal:

npm run --silent codex-worker -- \
  --config /absolute/path/to/project/.secure-mcp/runtime.config.json

Default worker command:

codex exec --sandbox workspace-write --ask-for-approval never --json -

Use this only when you explicitly want Codex to modify the workspace. The MCP request itself only creates or inspects task records. The worker child process does not inherit the full host environment; only configured safe keys/prefixes are passed through, and secret-like variable names are stripped.

Task creation supports idempotency keys and captures the relevant-file/Git baseline. The worker publishes a heartbeat, refuses stale relevant-file context by default, supports running-task cancellation, and records changed files, pre-existing changes, and a diff summary in the final result.

Configuration

Start from:

examples/config.example.json
examples/extensions.example.json

Important defaults:

  • HTTP server binds to 127.0.0.1

  • sandbox network is none

  • the host workspace is not mounted into the final sandbox; a filtered, disposable copy is writable so builds can create temporary outputs

  • root filesystem is read-only

  • Linux capabilities are dropped

  • no-new-privileges is enabled

  • memory, CPU, PID, timeout, and output limits are configured

  • audit logging is enabled

For a low-round-trip client flow, call workspace_bootstrap first. File list and search tools return opaque cursors, read_files applies aggregate budgets, and every result includes a structured nextAction when continuation or setup is needed.

Development

npm install
npm run lint
npm test
npm run build

Optional Docker e2e:

npm run test:e2e

This requires Docker and runs only the gated Docker sandbox e2e suite. Normal npm test keeps that suite skipped.

Useful docs:

Status

MCP RepoBridge is an early 0.1.x project. The core runtime, HTTP transport, Docker sandbox lifecycle, document Skill/trusted host MCP gateway, bridge adapter, and optional Codex handoff flow are in place.

The project is useful today, but interfaces and deployment guidance may evolve as it is tested against more real repositories and MCP clients.

License

Apache-2.0. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables repository-aware lifecycle management and controlled delegation of coding tasks to trusted worker harnesses via MCP, with execution isolation, recovery, and verified handoff.
      36 npm
      8
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables autonomous software-engineering tasks in a repository by coordinating filesystem, GitHub, database, and CI/CD tools through MCP, with a deterministic safety boundary for permissions, validation, timeouts, duplicate protection, and test verification.
      MIT