# Bridge Builder MCP Server
Local FastMCP server that exposes a two-agent Codex pipeline over stdio. It is designed to work against many repository types and programming languages by inferring stack details from manifests, source symbols, and repository structure.
## Quick Start
`bridge-builder` is a local command-backed MCP server. The MCP server is the
main product. Agent-specific wrappers sit on top of it:
- Codex: install the skill from
`.agents/skills/bridge-builder-delegate/SKILL.md`
- Claude Code: install the slash command from
`.claude/commands/bridge-builder.md`
Typical setup:
1. Install and run the server with `uv sync`.
2. Register the `bridge-builder` MCP server in your host config.
3. Copy the wrapper that matches your agent.
4. Paste the corresponding invocation pattern:
For Codex:
```text
Use the bridge-builder-delegate skill to:
<your implementation request>
```
For Claude Code:
```text
/bridge-builder <your implementation request>
```
## What This Server Does
The server exposes:
- `analyze_request(request, repo_path)`: inspects a repository and asks Codex to convert a request into a self-contained implementation prompt.
- `implement(prompt)`: runs a fresh Codex implementation pass with no prior context beyond the prompt.
- `run_pipeline(request, repo_path)`: runs both steps in sequence, saves the generated prompt to `.agent_prompts/`, and returns the implementation result.
- `run_here(request)`: runs the full pipeline against a configured default repository, intended for easy invocation from a Codex session.
- `prompts://history`: returns the 10 most recent saved prompts.
The pipeline separates planning from execution:
1. Agent 1 reads the repo and generates a precise implementation brief.
2. Agent 2 executes that brief in a separate Codex run.
3. The server can optionally run lightweight post-verification checks.
## Requirements
- Python `>=3.12`
- `codex` CLI installed and authenticated
- `uv` recommended for dependency management
## Installation
```bash
uv sync
```
If dependencies are not installed yet:
```bash
uv add fastmcp
```
## Run Locally
```bash
uv run python main.py
```
Or use the script entrypoint:
```bash
uv run bridge-builder
```
The server uses stdio transport by default, so it can be registered with any MCP-compatible host that supports launching a local command.
## MCP Host Configuration
Example config:
```json
{
"mcpServers": {
"bridge-builder": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/bridge-builder",
"bridge-builder"
]
}
}
}
```
You can also use `python` directly:
```json
{
"mcpServers": {
"bridge-builder": {
"command": "python",
"args": ["/absolute/path/to/bridge-builder/main.py"]
}
}
}
```
If your MCP host supports environment variables, you can also set a default target repository for the `run_here` tool:
```json
{
"mcpServers": {
"bridge-builder": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/bridge-builder",
"bridge-builder"
],
"env": {
"BRIDGE_BUILDER_DEFAULT_REPO": "/absolute/path/to/target/repo"
}
}
}
}
```
## Tool Usage
### `analyze_request`
Inputs:
- `request`: natural-language implementation request
- `repo_path`: absolute or user-expandable path to the target repository
Returns:
- a self-contained implementation prompt string
Example:
```json
{
"request": "Add a CLI flag to export results as JSON",
"repo_path": "/path/to/repo"
}
```
### `implement`
Inputs:
- `prompt`: the implementation prompt generated by `analyze_request`
Returns:
- a concise rendered result based on structured implementor output
Notes:
- the prompt must include `Repository root: /absolute/path`
- in normal usage, pass the output of `analyze_request` directly into `implement`
### `run_pipeline`
Inputs:
- `request`
- `repo_path`
Returns a dictionary with:
- `generated_prompt`
- `implementation_result`
- `post_verification` when local checks were run
### `run_here`
Inputs:
- `request`
Returns the same payload as `run_pipeline`, plus:
- `resolved_repo_path`
Notes:
- `run_here` uses `BRIDGE_BUILDER_DEFAULT_REPO` when set
- if `BRIDGE_BUILDER_DEFAULT_REPO` is not set, it falls back to the server process working directory when that differs from the bridge-builder app directory
- if neither source resolves a usable repository, the tool raises an error and you should use `run_pipeline` with an explicit `repo_path`
## Command vs Skill
This project is best treated as a local command-backed MCP server first.
Agent-specific wrappers sit on top of that server:
- Codex: use a skill wrapper
- Claude Code: use a slash command wrapper
The wrapper choice is about ergonomics, not capability. Both wrappers should
call the same `bridge-builder` MCP server tools.
## Agent Wrappers
### Codex
Codex should use a skill, not a slash command.
For repo-local Codex usage, this repository includes the skill at:
```text
.agents/skills/bridge-builder-delegate/SKILL.md
```
If you want to copy this skill into another repository, copy the template from:
```text
codex-skills/bridge-builder-delegate/SKILL.md
```
and place it at:
```bash
mkdir -p /path/to/target-repo/.agents/skills/bridge-builder-delegate
cp codex-skills/bridge-builder-delegate/SKILL.md \
/path/to/target-repo/.agents/skills/bridge-builder-delegate/SKILL.md
```
Then paste prompts like:
```text
Use the bridge-builder-delegate skill to:
Add a CLI flag to export results as JSON.
```
Or, if you prefer calling the MCP tool directly from Codex, paste:
```text
Use the bridge-builder MCP server and run:
run_pipeline(
request="Add X feature",
repo_path="/absolute/path/to/current/repo"
)
```
If you configured `BRIDGE_BUILDER_DEFAULT_REPO`, you can paste:
```text
Use the bridge-builder MCP server and run:
run_here(
request="Add a CLI flag to export results as JSON"
)
```
The Codex skill is written to:
- call `run_here(request)` when a default repo is configured
- otherwise call `run_pipeline(request, repo_path)` using the current Codex
session working directory
### Claude Code
Claude Code should use a slash command. This repository includes a project
command template at `.claude/commands/bridge-builder.md`.
To install it into another repository or your home-level Claude commands,
copy the file into one of these locations:
```bash
mkdir -p /path/to/target-repo/.claude/commands
cp .claude/commands/bridge-builder.md \
/path/to/target-repo/.claude/commands/bridge-builder.md
```
Or for a user-level install:
```bash
mkdir -p "$HOME/.claude/commands"
cp .claude/commands/bridge-builder.md \
"$HOME/.claude/commands/bridge-builder.md"
```
Then in Claude Code, type:
```text
/bridge-builder Add a CLI flag to export results as JSON.
```
The Claude command is written to:
- treat the slash-command arguments as the implementation request
- call `run_here(request)` when a default repo is configured
- otherwise call `run_pipeline(request, repo_path)` using the current working
directory
## Copy/Paste by Agent
Use these exact patterns depending on the agent you are in.
### Codex with skill installed
```text
Use the bridge-builder-delegate skill to:
<your implementation request>
```
### Codex without skill
```text
Use the bridge-builder MCP server and run:
run_pipeline(
request="<your implementation request>",
repo_path="/absolute/path/to/current/repo"
)
```
### Codex with `BRIDGE_BUILDER_DEFAULT_REPO` configured
```text
Use the bridge-builder MCP server and run:
run_here(
request="<your implementation request>"
)
```
### Claude Code with command installed
```text
/bridge-builder <your implementation request>
```
## How Repository Analysis Works
The orchestrator builds a compact repository digest before calling Codex. It includes:
- file tree up to 3 levels
- README contents when present
- git status when available
- manifest and build summaries
- representative source-file symbols across multiple languages
- a small number of selected full source files
This makes the server general-purpose instead of being tied to one stack.
## Configuration
Environment variables:
```bash
export BRIDGE_BUILDER_ORCHESTRATOR_MODEL=gpt-5.4
export BRIDGE_BUILDER_IMPLEMENTOR_MODEL=gpt-5.4
export BRIDGE_BUILDER_ORCHESTRATOR_REASONING=high
export BRIDGE_BUILDER_IMPLEMENTOR_REASONING=medium
export BRIDGE_BUILDER_CODEX_TIMEOUT_SECONDS=1800
export BRIDGE_BUILDER_DEFAULT_REPO=/absolute/path/to/target/repo
export BRIDGE_BUILDER_ENABLE_POST_VERIFY=1
export BRIDGE_BUILDER_POST_VERIFY_TIMEOUT_SECONDS=300
export BRIDGE_BUILDER_ALLOW_PACKAGE_SCRIPT_VERIFY=0
```
Default behavior:
- Agent 1 uses `gpt-5.4` with `high` reasoning
- Agent 2 uses `gpt-5.4` with `medium` reasoning
- both agents run with `codex exec --ephemeral`
## Post-Verification
After `run_pipeline`, the server can run lightweight local checks based on the target repo and touched files. Current built-in checks include:
- Python: `python3 -m py_compile`
- Rust: `cargo check`
- Go: `go test ./...`
`npm run ...` verification is disabled by default because package scripts are arbitrary code. Enable it only if you trust the target repository.
The pipeline does not rely only on the model's reported `touched_files`. `run_pipeline` also snapshots the repository before and after implementation and merges detected file changes into post-verification input.
## Auditing
Every generated implementation prompt from `run_pipeline` is saved under:
```text
.agent_prompts/
```
The server ensures `.agent_prompts/.gitignore` contains `*`, so saved prompt history is skipped by Git by default.
Use the `prompts://history` resource to inspect the most recent saved prompts.
## Development Checks
Useful local checks while editing this server:
```bash
python3 -m py_compile main.py
uv run python -m py_compile main.py
```