# AutoPatch — Self-Healing Debugging Agent (MCP Server)

AutoPatch is a closed-loop agent: it runs a repo's tests, and if something
fails, it searches that repo's own git history for how a similar bug was
fixed before, generates a patch guided by that precedent, applies it, and
re-runs the tests — looping until the suite passes or it gives up after a
capped number of attempts. It doesn't just answer questions about code, it
takes real actions (running pytest, writing files) and reacts to real
feedback (test results), which is the core pattern behind current
autonomous software-engineering agents (Devin, OpenHands, SWE-agent).

Everything is also exposed as an MCP server, so any MCP client (Claude
Desktop, Cursor, a LangGraph agent via `langchain-mcp-adapters`) can drive
the same loop through four tools instead of the Streamlit UI.

## Architecture

```
                 ┌─────────────┐
        ┌───────▶│  run_tests  │◀────────────────┐
        │        └──────┬──────┘                 │
        │           pass │ fail                   │
        │               ▼                        │
        │      ┌───────────────────┐              │
   __END__      │ retrieve_precedent│  ChromaDB over the repo's own
                │  (ChromaDB search) │  git log (commit msgs + diffs)
                └─────────┬──────────┘             │
                          ▼                        │
                 ┌─────────────────┐               │
                 │  propose_patch   │  Groq LLM, function-level fix,
                 │  (Groq + Llama)  │  guided by the retrieved precedent
                 └─────────┬────────┘               │
                          ▼                        │
                 ┌─────────────────┐               │
                 │   apply_patch    │──────────────┘
                 └─────────────────┘
```

Implemented as a LangGraph `StateGraph` with a conditional edge that routes
back into the loop on failure (capped at `MAX_PATCH_ITERATIONS`) and out to
`END` on success.

## Why function-level patching, not whole-file rewrites

Early design considered asking the LLM to return the entire corrected
file. Rejected: LLMs occasionally truncate or silently drop unrelated
functions when asked to reproduce a whole file. Instead, the LLM only ever
returns the single corrected function; `src/code_surgery.py` splices it
back into the real file via AST-based function-boundary detection, and the
diff shown in the UI is computed with `difflib` against the actual bytes
that get written — what you see is guaranteed to be what's applied.

## The demo repo

`demo_repo/` is a tiny, real git repository (own history, own commits) with
a `calculator` package. Its git history contains a genuine bug-fix commit:
`divide()` originally divided by `(b - 1)` instead of `b`, fixed in a later
commit. `demo_repo/bug_scenarios/` lets you re-inject that same class of
bug (and two others) into the working tree at will, so AutoPatch always has
something fresh to heal, and — for the `average_offbyone` scenario — a real
historical precedent to retrieve and learn from.

## Setup

```bash
git clone <your-repo-url>
cd autopatch
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env: set GROQ_API_KEY (and optionally GROQ_API_KEY_FALLBACK)

python scripts/seed_git_history.py   # builds demo_repo's real git history, once
```

## Running it

**Streamlit dashboard** (recommended for a live demo):
```bash
streamlit run streamlit_app.py
```
Pick a bug scenario in the sidebar, click "Inject bug," then "Run AutoPatch
agent" — watch it test, retrieve, patch, and re-test live.

**CLI**:
```bash
python main.py --scenario average_offbyone
```

**MCP server** (stdio transport, for Claude Desktop / Cursor / any MCP client):
```bash
python -m src.mcp_server
```
Add to your MCP client config, e.g. Claude Desktop's `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "autopatch": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/autopatch",
      "env": {"GROQ_API_KEY": "..."}
    }
  }
}
```

**REST API** (for non-MCP clients, e.g. a CI webhook):
```bash
uvicorn src.rest_api:app --reload
# POST /inject {"bug_id": "average_offbyone"}
# POST /heal
```

## Tests

```bash
pytest tests/ -v
```
`test_patcher.py` and `test_agent_graph.py` use a fake Groq client (no
API key or network needed); `test_executor.py` runs the real demo repo's
test suite as a subprocess.

## Tech stack

Python, LangGraph (cyclic state graph with conditional routing), MCP
(FastMCP), ChromaDB (git-history vector index), Groq (Llama 3.3, with
automatic fallback to a secondary API key on rate limits), FastAPI,
Streamlit, GitPython, pytest, `difflib`/`ast` for source-level patching.

## Deployment

See `render.yaml` / `Procfile` — deploys as a single Render web service
running the Streamlit dashboard (the MCP server and REST API run
in-process alongside it for the demo; run `src.mcp_server` separately for
real MCP-client integration).