# blastradius-mcp

Multi-hop microservice and dependency triage agent. It models a service topology in **Neo4j**, exposes triage and remediation tools over **FastMCP**, and drives them with a **LangGraph** workflow that pauses for human approval before anything mutating runs.

## What it does

| Capability | Module | Summary |
|---|---|---|
| Directional lineage | `app/services/lineage_service.py` | Upstream dependency chain or downstream blast radius, with direction rules per edge type, plus a Mermaid diagram. |
| Causal ranking | `app/services/hypothesis_service.py` | Scores root-cause candidates from four signals: graph hop distance, temporal delta, git-diff vs stack-token overlap, and trace match. |
| Redundancy-aware risk | `app/services/risk_service.py` | Composite score from PageRank, business tier, consumer count and error ratio. A healthy `FALLBACK_TO` edge applies a 0.35x multiplier. |
| Safe remediation | `app/services/remediation_service.py` | Stages a dry-run plan with a rollback command, then executes only with approval and the `remediation:execute` scope. Writes a `RemediationAudit` node. |
| Triage agent | `app/agent/triage_graph.py` | LangGraph flow: investigate, risk and stage, `interrupt()` for approval, execute. |

## Project layout

```
blastradius-mcp/
├── pyproject.toml
├── docker-compose.yml          # Neo4j 5.23 community
├── demo_runner.py              # End-to-end demo
├── manifests/
│   ├── topology_seed.yaml      # Services, workers, queues, datastores, configs, schemas
│   └── incident_fixtures.json  # Simulated git diffs and error telemetry
└── app/
    ├── main.py                 # FastAPI app, mounts FastMCP at /mcp
    ├── config.py               # Pydantic settings
    ├── models/schemas.py       # Pydantic models and enums
    ├── db/                     # Neo4j client and Cypher queries
    ├── ingestion/seed_graph.py # YAML and fixtures loader, PageRank
    ├── services/               # Lineage, hypothesis, risk, remediation
    ├── mcp_server/             # FastMCP server and tools
    └── agent/triage_graph.py   # LangGraph workflow
```

## Requirements

- Python 3.14 (pinned in `.python-version`)
- [uv](https://docs.astral.sh/uv/)
- Docker, for Neo4j

## Quick start

```powershell
# 1. Start Neo4j
docker compose up -d

# 2. Install dependencies
uv sync

# 3. Run the end-to-end demo (seeds the graph, runs the agent, approves a plan)
uv run python demo_runner.py

# 4. Or start the API and MCP server
uv run uvicorn app.main:app --reload --port 8000
```

- Swagger UI: http://localhost:8000/docs
- MCP endpoint: http://localhost:8000/mcp
- Neo4j Browser: http://localhost:7474

> [!WARNING]
> Seeding runs `MATCH (n) DETACH DELETE n`. It wipes the entire database, including audit records. Only point it at a disposable Neo4j instance.

## Configuration

Settings are read from environment variables or a `.env` file.

| Variable | Default |
|---|---|
| `NEO4J_URI` | `bolt://localhost:7687` |
| `NEO4J_USER` | `neo4j` |
| `NEO4J_PASSWORD` | `blastradius123` |
| `APP_ENV` | `development` |

The default password matches `docker-compose.yml` and is for local development only.

## HTTP API

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/v1/seed` | Reset and seed the graph |
| GET | `/api/v1/lineage/{node_id}?mode=&max_hops=` | Lineage traversal |
| GET | `/api/v1/risk/{node_id}` | Composite risk for a node |
| POST | `/api/v1/triage/start` | Run the agent until it pauses for approval |
| POST | `/api/v1/triage/approve` | Resume the agent with an approval decision |

## MCP tools

| Tool | Type | Scope |
|---|---|---|
| `trace_directional_lineage` | Read-only | `triage:read` |
| `rank_causal_hypotheses` | Read-only | `triage:read` |
| `calculate_composite_risk` | Read-only | `triage:read` |
| `stage_remediation_plan` | Staging, non-destructive | `remediation:stage` |
| `execute_remediation_plan` | Mutating | `remediation:execute` |

## Risk scoring

```
raw   = 0.30*pagerank + 0.30*tier_weight + 0.25*consumer_ratio + 0.15*error_ratio
final = raw * (0.35 if healthy fallback else 1.0)
```

Severity bands: `P0 >= 0.75`, `P1 >= 0.50`, `P2 >= 0.25`, `P3 < 0.25`.
Tier weights: `TIER_1 1.0`, `TIER_2 0.75`, `TIER_3 0.40`, `TIER_4 0.10`.

## Known limitations

- `app/mcp_server/server.py` (scope interceptor) is not implemented yet. Scope checks currently happen only inside `execute_approved_plan`, using scopes supplied by the caller.
- Remediation is simulated: executing a plan updates the audit node but does not run `git revert`.
- The LangGraph checkpointer is in-memory, so paused threads are lost on restart.

## License

Apache License 2.0. See [LICENSE](LICENSE).