tfmcp 是一个实验性的 CLI 工具，基于 Model Context Protocol（MCP），旨在让 AI 助手管理和操作 Terraform 环境。它通过本地 Terraform 工作流，帮助 AI 助手检查项目、准备执行、审查已保存的计划、应用该计划并检查结果。Registry 和 HCP/TFE 工具支持这些本地工作流。
主要能力：
- 读取 Terraform 配置文件
- 分析 Terraform 计划输出
- 应用 Terraform 配置
- 管理 Terraform 状态
- 创建和修改 Terraform 配置
当前版本 v0.2.4 的新特性包括：以与 apply 相同的已保存计划和权限检查审查 destroy 计划；已保存计划的列出和丢弃以回收 64 个计划容量；保留 apply 结果、失败/未知结果及恢复指导；对完整和命名输出查询进行敏感输出脱敏；升级至 RMCP 3.5.0，更新依赖和镜像，保留 Rust 1.88 MSRV。
使用方式： 用户需安装 Rust 1.88.0+（Rust Edition 2024）和 Terraform CLI 1.15.8 并确保在 PATH 中可用，还需要一个兼容 MCP 的 AI 客户端（如 Claude Desktop 或 Codex），Docker 为可选项。安装可通过 cargo install tfmcp 或使用 Docker 构建镜像 docker build -t tfmcp .。
与 Claude Desktop 集成：找到 tfmcp 可执行文件路径（which tfmcp），在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加配置，重启 Claude Desktop 并启用 tfmcp 工具。tfmcp 会在 ~/terraform 自动创建示例 Terraform 项目（如果不存在），确保 Claude 可以立即开始使用 Terraform。
本地计划/应用工作流：以 tfmcp --dir /path/to/project mcp --toolsets terraform 启动。默认工具集支持准备和计划审查；terraform 工具集还暴露初始化和受控的本地写入。调用 prepare_terraform_change 检查选定目录、Terraform 版本、工作区、后端、配置有效性和状态可读性。必要时用 init_terraform 初始化，然后重复准备。调用 get_terraform_plan 获取计划，结果包含 plan_id、target、created_at、has_changes 和脱敏的 Terraform JSON 计划字符串。将返回的 plan_id 传递给 analyze_plan、review_terraform_plan 和 summarize_plan_for_pr。审查批准后，调用 apply_terraform 并传入 plan_id 和 auto_approve:true，同时服务器必须已配置 TFMCP_ALLOW_DANGEROUS_OPS=true 和 TFMCP_ALLOW_AUTO_APPROVE=true。检查 apply 结果中的 success、status、exit_code、diagnostics、state_verified 和 recovery.next_steps。失败或超时后，检查状态并创建新计划；尝试过的 ID 不能再次应用。
从 v0.2.2 迁移：apply_terraform 需要 plan_id；仅提供 auto_approve 的调用现在返回解释性错误。批准在调用前的客户端进行，因为 Terraform 不接收交互输入。
对于已审查的销毁：使用 get_terraform_plan({"destroy":true}) 创建计划，审查其 plan_id，然后调用 destroy_terraform 并传入该 ID 和 auto_approve:true。服务器还必须设置 TFMCP_DELETE_ENABLED=true，以及两个 apply 权限。将 destroy 计划传递给 apply_terraform 会执行相同的权限。destroy 不能与 refresh_only 或 replace 组合。从 v0.2.3 迁移：destroy_terraform 现在需要已保存的 destroy 计划；它不再创建未审查的计划或等待提示。
使用 list_terraform_plans 查找保留的 ID 及其目标和状态。使用 discard_terraform_plan({"plan_id":"<ID>"}) 删除不需要的计划的临时文件并释放容量。丢弃不会更改基础设施、取消操作或回滚 apply；在移除记录前检查失败或未知结果。这些工具在默认和 Terraform 工具集中可用。
已保存计划使用私有临时目录，并绑定到项目、工作区、已初始化后端元数据、Terraform 版本和提供程序锁文件。计划 ID 仅在当前服务器进程中有效，最多保留 64 个计划。正常服务器关闭会删除临时文件。failed 表示 Terraform 返回非零退出码，可能已应用部分更改。outcome_unknown 表示未获得确定的退出结果，包括超时或取消。两者都阻止重新应用同一计划，并包含恢复指导：确认操作已停止，检查记录的目标和实际资源，解决原因，然后生成并审查新计划。不执行回滚或自动重试。当请求在结果可保留之前被取消时，apply_result 为 null。状态验证检查资源地址，而非所有属性值或输出值。状态检索等待正在进行的操作完成；此版本不提供实时进度和重启恢复。
tfmcp 为 AI 助手提供以下 MCP 工具：核心 Terraform 操作、工作区与状态（v0.1.9）、代码与输出（v0.1.9）、分析与安全、HCP Terraform / Terraform Enterprise（只读）、HCP Terraform / Terraform Enterprise（受控操作）、日志和故障排除。
日志位于 ~/.tfmcp/audit.log。常见问题：Claude 无法连接到服务器（确保配置中 tfmcp 可执行文件路径正确）；Terraform 项目问题（tfmcp 自动创建示例项目）；方法未找到错误（tfmcp 声明并实现 tools/list、resources/list、resources/templates/list 和 resources/read）；Docker 问题（确保容器具有正确的卷挂载和权限）。
环境变量包括核心配置（TERRAFORM_DIR、TFMCP_LOG_LEVEL、TFMCP_DEMO_MODE、TFMCP_COMMAND_TIMEOUT_SECONDS）、安全配置（ENABLE_TF_OPERATIONS、TFMCP_ALLOW_DANGEROUS_OPS、TFMCP_DELETE_ENABLED、TFMCP_ALLOW_AUTO_APPROVE、TFMCP_MAX_RESOURCES、TFMCP_AUDIT_ENABLED、TFMCP_AUDIT_LOG_FILE、TFMCP_AUDIT_LOG_SENSITIVE）、HCP Terraform / Terraform Enterprise（TFE_ADDRESS、TFE_TOKEN、TFE_SKIP_TLS_VERIFY、TFE_MAX_RESPONSE_BYTES）以及传输配置（TRANSPORT_MODE、TRANSPORT_HOST、TRANSPORT_PORT、MCP_ENDPOINT、MCP_HEALTH_ENDPOINT、MCP_METRICS_ENDPOINT、MCP_SESSION_MODE、MCP_HEARTBEAT_INTERVAL、MCP_CORS_MODE、MCP_ALLOWED_ORIGINS、MCP_ALLOWED_HOSTS、MCP_ORGANIZATION_ALLOWLIST、MCP_RATE_LIMIT_GLOBAL、MCP_RATE_LIMIT_SESSION、MCP_TLS_CERT_FILE、MCP_TLS_KEY_FILE）。
安全考虑：tfmcp 包含面向生产环境的综合安全功能，如访问控制（自动阻止生产/敏感文件模式）、操作限制（默认禁用危险操作）、资源限制、审计日志、目录验证。最佳实践包括默认安全、审查计划、IAM 边界、审计监控、文件模式保护、Docker 安全。
贡献指南：欢迎提交 PR。分叉仓库，创建特性分支，启用仓库管理的快速预提交检查（git config core.hooksPath .githooks），运行完整正确性检查（cargo fmt --all -- --check、cargo clippy --all-targets --all-features -- -D warnings、cargo test --locked --all-targets --all-features），提交更改，推送分支，打开 PR。预提交钩子始终检查暂存空白，并针对受影响文件有条件地运行 cargo fmt、actionlint、Registry 元数据验证、模块耦合和重复代码检查。可选架构工具在 Release.sh 中仍为强制，安装 cargo-coupling 和 similarity-rs 以运行相同的快速检查。
限制：项目仍处于活跃开发阶段，在生产环境中需谨慎审查所有操作。状态验证不检查所有属性值或输出值。不提供实时进度和重启恢复。计划 ID 仅在当前服务器进程中有效。
