# 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

```mermaid
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.

## Quick start

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

```bash
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:

```bash
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.

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

## Development

```bash
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

```text
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