cloud-governance-mcp

A read-only MCP server that explains proposed Terraform infrastructure changes. It reads an existing plan JSON file and returns resource identities, action/type/ mode counts, and coverage warnings through analyze_terraform_plan.

Status: the first analysis increment (A1–A7) is complete. 521 tests pass, including real MCP stdio and example-client tests. Package version is 0.1.0.dev0; the full three-tool v0.1 governance MVP remains in progress. OPA/Rego policy evaluation is the next development increment.

Try it locally

From the repository directory, with uv installed:

uv sync --locked --no-editable
uv run --locked --no-editable python examples/client.py --list-tools
uv run --locked --no-editable python examples/client.py

The first call lists analyze_terraform_plan. The second analyzes our synthetic mixed plan: 7 resources, 4 managed changes, and partial coverage because one inventory resource has no reported action. Compare the input plan with the full example response.

The example client starts and stops its own server. No second terminal, AI model, API key, AWS credentials, Terraform or OPA is needed. Initial dependency/interpreter installation may need internet access; analysis itself is local.

Follow the hands-on walkthrough to understand the report, try other fixtures and safe failures, supply your own plan, and connect an MCP host. The client source shows the official SDK calls.

Related MCP server: terraform-best-practices-mcp-server

Run the server for an MCP host

After setup, launch with an existing absolute directory containing plan files:

uv run --locked --no-editable cloud-governance-mcp --allowed-root /absolute/path/to/plans

The host calls analyze_terraform_plan with {"plan_path": "plan.json"}. Repeat --allowed-root for more directories; relative plan paths use the first root. The process waits for MCP messages on stdin, and stdout carries protocol frames only. There is no terminal prompt or HTTP page. See host process settings and all CLI options.

Supported behavior and boundaries

• Terraform plan JSON format major 1; state JSON, HCL and binary plans are rejected.

• Generic provider identities, recursive modules and exact numeric/string instance keys. Inventories merge by resource address without double counting.

• Create, update, delete, both replacement orders, no-op and data-source read. Inventory-only resources remain unreported; they are never guessed to be no-op.

• Deterministic public reports with fixed warnings/errors. complete/partial describes coverage of the supplied plan, not compliance or deployment state.

• Explicit allowed roots; no traversal, symlinks beneath roots, special files or implicit current-directory access. Input/depth/resource/output limits and one active analysis are enforced. Run --help for startup options.

• Attribute values, variables, outputs and internal sensitive/unknown paths are absent from responses. Resource identities are intentionally returned.

• The server never executes Terraform, applies changes, or connects to AWS. Provide a completed, stable plan file; it does not freeze concurrent file writes.

Development uses Python 3.14.7 with locked dependencies and a src/ layout. The package requires Python 3.14+. Secure file loading targets macOS/Linux; macOS arm64 is verified, Linux execution remains unverified here, and unsupported platforms fail startup. The regular-install --no-editable workflow avoids an observed local macOS editable-import issue. See development notes.

Verification

uv run --locked --no-editable pytest
uv run --locked --no-editable ruff check .
uv run --locked --no-editable ruff format --check .
uv build

The acceptance record maps AN-01–AN-15 to tests and records versions, independent wheel/stdio checks, and tested limitations. The synthetic fixtures use fake values; illustrative Terraform configuration is not executed by tests. No OPA setup or policy tests belong to this analysis increment.

Project progression

1. Implemented: analyze_terraform_plan for proposed infrastructure changes.

2. Planned: evaluate_terraform_policies, starting with one RDS encryption policy using OPA/Rego and the shared parsing foundation.

3. Planned: list_policies, then the remaining initial policy families.

AWS connectivity is planned after v0.1. No cloud adapter, Docker, CI workflow, drift, cost or retrieval capability is implemented in this increment.

• Requirements and acceptance criteria

• Architecture and decisions

• Specification 001

• Implementation plan

• Release roadmap

• Repository guidance

Stack: Python 3.14+, the official MCP Python SDK, Pydantic, AnyIO, uv, pytest and Ruff. Policy evaluation will introduce OPA/Rego.

License: Apache 2.0.