# tfplan-mcp the Hard Way

Build an MCP server that lets an AI risk-review a Terraform / OpenTofu plan, from scratch, in
seven small modules. You end with a working miniature of
[tfplan-mcp](https://github.com/0xmortuex/tfplan-mcp): it reads a plan file, summarizes it,
ranks the dangerous changes, diffs one resource with secrets masked, and compares two plans,
all over MCP stdio, and it never runs terraform.

Every module has:

- `README.md` - the why, in plain prose
- code you can read in one sitting
- `main.py` - runs the code and **asserts** the result, so the claims in the README are checked
- `break-it.md` - challenges that make you find the sharp edges yourself

`verify.py` runs every `main.py` for real. CI does the same on Ubuntu and Windows.

## Run it

```
python -m venv .venv
.venv/Scripts/activate        # Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python verify.py              # all seven modules
python verify.py 03 05        # just these
python 03-risk-heuristics/main.py
```

Only module 07 needs the `mcp` package. Modules 01-06 are plain Python.

## Modules

| # | Module | You learn |
| --- | --- | --- |
| 01 | [The plan JSON](01-the-plan-json) | what `terraform show -json` contains, and refusing things that are not plans (a state file looks almost identical) |
| 02 | [Action semantics](02-action-semantics) | create/update/delete/replace, why a replace is two actions and the order matters, no-ops that are really moves and imports |
| 03 | [Risk heuristics](03-risk-heuristics) | ranking changes: stateful types, new exposure only (compare before and after), tags-only demotion |
| 04 | [Diffing nested values](04-diffing-nested-values) | walking before/after/after_unknown together, paths like `ingress[1].cidr_blocks[0]`, `(known after apply)` |
| 05 | [Masking secrets](05-masking-secrets) | two independent layers: Terraform's sensitivity masks and name heuristics |
| 06 | [Comparing plans](06-comparing-plans) | new / removed / changed action / changed values between two plans |
| 07 | [The MCP wrapper](07-the-mcp-wrapper) | tools, a directory sandbox, errors an agent can read, and a plant-a-secret test over real stdio |

The sample plans in [plans/](plans) are small hand-written `terraform show -json` documents
(format_version 1.2). The fake secret in them is `TUTORIAL-hunter2`; the tests search every
output for it.

MIT licensed.