mcp-tfstate-reader: Instructions file for Claude Code

CLAUDE.md — mcp-tfstate-reader

This file helps Claude Code understand the project structure and conventions for future sessions.

Project overview

mcp-tfstate-reader is a local MCP (Model Context Protocol) server written in Python. It parses Terraform .tfstate files and exposes five tools that allow AI agents to audit infrastructure for security misconfigurations without needing live cloud credentials.

Transport: stdio (standard input/output).

---

Directory structure

mcp-tfstate-reader/
├── src/
│   └── mcp_tfstate_reader/
│       ├── __init__.py          # Package version
│       └── server.py            # All MCP tool logic (single file)
├── tests/
│   ├── __init__.py
│   ├── fixtures/
│   │   └── sample.tfstate       # Comprehensive fixture covering all audit rules
│   └── test_server.py           # pytest tests — imports internals directly
├── pyproject.toml               # Build config (hatchling), deps, pytest settings
├── Makefile                     # setup / build / start / test / clean
├── README.md                    # User-facing docs with MCP config examples
├── CLAUDE.md                    # This file
└── .gitignore

---

Key design decisions

1. Single-file server — all tool logic lives in src/mcp_tfstate_reader/server.py. Keep it that way unless the file exceeds ~500 lines.

2. No external dependencies beyond mcp SDK for runtime, and pytest + pytest-asyncio for tests. Do not add boto3, pydantic, or other libraries without a strong reason.

3. Private helpers are directly importable in tests — the test file imports _load_tfstate, _iter_resources, _list_resources, _audit_security, _get_resource_detail, _summarize_state, and _compare_states directly. Keep these functions at module level.

4. asyncio_mode = "auto" is set in pyproject.toml, so @pytest.mark.asyncio is optional but harmless to include.

5. Resource address format follows Terraform convention: <type>.<name> for root module, <module>.<type>.<name> for nested modules. Index suffixes ([0], ["key"]) are appended for multi-instance resources.