ForgeMCP

ForgeMCP is a bounded, MCP-native runtime for autonomous software-engineering tasks. It coordinates filesystem, GitHub, database, and CI/CD tools through the Model Context Protocol, but places a deterministic safety boundary between model-generated plans and side effects.

The project focuses on the parts that make an agent trustworthy in a real repository: typed plans, explicit permissions, argument-schema validation, per-tool timeouts, duplicate mutation protection, incremental context retrieval, event logs, step limits, and fresh test evidence before a task can be marked complete.

Architecture

flowchart LR
    T[Task] --> I[Incremental repo index]
    I --> P[Planner]
    P -->|typed Action| G[Safety gateway]
    G -->|validated call| R[Tool registry]
    R --> F[Filesystem MCP]
    R --> H[GitHub MCP]
    R --> D[Database MCP]
    R --> C[CI/CD MCP]
    F & H & D & C -->|Observation| P
    P -->|completion claim| Q[Test gate]
    Q -->|fail: continue| P
    Q -->|pass| O[Agent result]

Safety invariants

• A task receives no permission implicitly. Every MCP tool declares the permissions it needs.

• Every argument object is checked against the tool's JSON Schema before the server sees it.

• Each tool has a hard timeout, and three consecutive failures stop the run by default.

• Identical mutating calls are rejected within a task, preventing accidental replay.

• The planner cannot choose the verification command. A configured test gate owns it.

• The runtime stops at the task's step budget even if the planner keeps requesting actions.

Context selection

IncrementalRepoIndex hashes repository files and only reindexes additions or content changes. It combines lexical relevance, path matches, recent Git diffs, and structural files, then clips excerpts to a hard token budget. PostgresIndexStore persists the index across runs; the in-memory store is useful for tests and short-lived jobs.

Related MCP server: MCP RepoBridge

Quick start

Requirements: Python 3.11+, Node.js for npm-hosted MCP servers, and optionally PostgreSQL 16.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev,postgres]'
cp examples/forgemcp.example.json forgemcp.json
docker compose up -d postgres
export OPENAI_API_KEY=your_key
forgemcp --config forgemcp.json run \
  --repository /path/to/repo \
  --allow filesystem:read \
  --allow filesystem:write \
  --allow process:exec \
  "Fix the parser regression and add a focused test"

Use the least permission necessary. GitHub writes, database writes, and CI triggers must be granted independently.

Refresh only the repository index:

forgemcp --config forgemcp.json index /path/to/repo

Configuration

ForgeMCP uses JSON so configuration is validated without another parser dependency. Environment variables in env are additions to the subprocess environment; secrets should be injected by the host and never committed. examples/forgemcp.example.json demonstrates four independently permissioned MCP servers. Replace commands and tool policy names with those exposed by your chosen servers.

The planner uses the OpenAI Responses API with Pydantic Structured Outputs. Requests set store=false, cap planner output, and submit runtime policy as developer instructions; MCP side effects still pass through ForgeMCP's local gateway rather than being executed by model output.

{
  "model": "gpt-5",
  "max_steps": 12,
  "context_token_budget": 4000,
  "postgres_dsn": "postgresql://forgemcp:forgemcp@localhost:5432/forgemcp",
  "test_command": ["pytest", "-q"],
  "servers": []
}

Development

pip install -e '.[dev,postgres]'
ruff check .
pytest --cov=forgemcp --cov-report=term-missing

The benchmark harness in benchmarks/ runs a reproducible held-out routing suite against fake MCP servers. It exists to catch orchestration regressions without external credentials; it is not a substitute for measuring a configured model on your own repositories.

The frozen keyword baseline currently resolves 10 of 14 tasks (71.4%) end to end. Reproduce the checked-in result with python -m benchmarks.run. The four unresolved paraphrases are retained as regression targets rather than tuned away.

Project layout

src/forgemcp/
  runtime.py       bounded Plan–Act–Observe loop
  safety.py        permission, schema, timeout, and replay checks
  registry.py      concurrent discovery and qualified-name routing
  context.py       incremental index and token-budget selection
  mcp_client.py    official stdio MCP adapter and in-memory fake
  gates.py         deterministic completion verification
tests/             unit and end-to-end orchestration tests
benchmarks/        reproducible held-out routing harness

License

MIT