OpenTofu Test

opentofu-test-mcp

适用于 OpenTofu / Terraform 原生测试框架（.tftest.hcl / .tfmock.hcl）的 MCP 服务。

LLM Agent 擅长编写 Terraform，但经常会生成有问题的 run、assert 和 mock_provider 块，因为测试框架的语法虽然简单，却容错性很低。此服务为 Agent 提供准确的块参考，根据模块的实际变量和输出搭建测试框架，根据已安装的提供程序架构生成模拟提供程序，静态验证测试文件并运行测试套件，让 Agent 无需猜测即可编写和检查测试。

如果存在 tofu CLI，则使用它；否则回退到 terraform。

工具

工具	功能
tf_explain_test_schema	提供测试框架块（run、assert、mock_provider、expect_failures 等）的参考和示例。主题为空时返回概览。无需 CLI。
tf_scaffold_test	读取模块的变量和输出，并生成 .tftest.hcl 起始文件，其中包含一个 run 块、针对每个输出的断言，以及必需变量的占位符。
tf_gen_mock_provider	对已初始化的模块运行 providers schema -json，并生成一个 mock_provider 块，其中已为计算属性预填 mock_resource 默认值。
tf_validate_test	静态检查 .tftest.hcl（按路径或原始内容）：无效的 command、缺少 condition/error_message 的断言、重复的 run 名称，以及没有 run 块。不会运行 OpenTofu。
tf_run_tests	运行 tofu test -json，并返回精简的通过/失败摘要及每个 run 的状态。

安装

go install github.com/ogormans-deptstack/opentofu-test-mcp@latest

由架构和运行工具驱动的功能需要在 PATH 中安装 tofu（优先）或 terraform。tf_explain_test_schema 和 tf_validate_test 不需要这两者。

macOS、Linux 和 Windows（amd64/arm64）的预编译二进制文件随校验和一起发布在 GitHub Releases 上。 原生二进制文件仍需要另行安装 OpenTofu 或 Terraform CLI。

容器

发布工作流会发布一个内含 OpenTofu 的镜像：

docker run --rm -i -v "$PWD:/workspace" \
  ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0

请使用 -i，不要使用 -t：标准输入输出必须保持为未修改的 JSON-RPC 流。传给工具的模块路径必须是容器路径，例如 /workspace，而非主机路径。 只挂载你信任的模块：原生测试可能会应用真实基础设施并执行提供程序代码。该镜像不会继承主机上的云凭据。

配置（客户端）

{
  "mcpServers": {
    "opentofu-test": {
      "command": "opentofu-test-mcp"
    }
  }
}

对于 Docker，请将 command 配置为 docker，并将 args 配置为 ["run", "--rm", "-i", "-v", "/absolute/module/path:/workspace", "ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0"]。

示例

让 Agent“为此模块搭建测试框架并运行测试”：

1. tf_scaffold_test { "dir": "." } → 生成 .tftest.hcl 骨架。
2. tf_gen_mock_provider { "dir": "." } → 生成 mock_provider 块（模块必须已初始化）。
3. tf_validate_test { "path": "main.tftest.hcl" } → 检查是否存在结构问题。
4. tf_run_tests { "dir": "." } → passed=1 failed=0 errored=0 skipped=0。

开发

go test ./...
go vet ./...

使用 Inspector 自动检查 MCP

需要在 PATH 中安装 Node.js 22.19+、Go 和 OpenTofu 1.13.1。Inspector 版本固定在 package-lock.json 中；Node 是开发工具，而不是服务的运行时 依赖。

npm ci
go build -o dist/opentofu-test-mcp .
npm run test:mcp

这会通过 Inspector CLI 在真实 stdio 上启动已构建的服务。它会检查初始化、准确的五项工具清单、 可移植的输入架构（tools/list --strict）、结构化输出、全部五项 工具、缺少输入时的错误，以及通过和故意失败的原生测试。测试夹具使用 OpenTofu 内置的 terraform_data 提供程序，因此不需要云凭据或下载提供程序。失败的夹具是有意设置的。 测试会在临时副本中运行，并使用 Inspector 的内存密钥存储。

使用相同的测试套件检查容器：

docker build -t opentofu-test-mcp:local .
MCP_IMAGE=opentofu-test-mcp:local npm run test:mcp

要检查其他构建，请设置 MCP_SERVER=/absolute/path/to/opentofu-test-mcp。 CI 除 Go 竞态测试外，还会运行原生和容器冒烟测试。

如需单独检查或交互式调试：

# Machine-readable tool inventory; non-zero on schema portability errors.
npx --no-install @modelcontextprotocol/inspector --cli ./dist/opentofu-test-mcp \
  --method tools/list --strict --format json --stored-auth-only

# A single tool call, without starting a browser.
npx --no-install @modelcontextprotocol/inspector --cli ./dist/opentofu-test-mcp \
  --method tools/call --tool-name tf_explain_test_schema \
  --tool-args-json '{"topic":"run"}' --format json --stored-auth-only

# Web Inspector for inspecting requests, responses, and schemas.
npm run inspect

提交 MCP 更改前，请使用一次性夹具复现行为，为回归问题及其错误路径添加断言，然后运行 Go 和 Inspector 测试套件。断言 JSON 结果，而不只是进程退出状态： 对于 isError: true，Inspector 的退出码为 5；对于严格架构失败，退出码为 6； 但有效的 tf_validate_test 响应（其中 valid: false）或原生测试 摘要（其中 failed > 0）仍会成功退出。Inspector 检查是对单元测试的补充， 而非替代；它们无法证明每个 Terraform 表达式在语义上都正确，也无法保证 与所有 MCP 客户端兼容。

Inspector 文档 还介绍了 TUI 和实验性的 mcpdo 持久连接客户端。对于此服务的无状态请求，CLI 已足够； 对于未来依赖会话的流程，请使用持久客户端。固定版本的 CLI 默认使用旧版 协议时代，与服务 SDK 相匹配；在先升级并测试服务之前，不要强制进行现代时代协商。 保持 Web UI 的默认环回绑定和身份验证处于启用状态，并且不要将密钥放入夹具 文件或捕获的记录中。

发布

1. 同时更新 server.json 的顶层版本和 OCI 标识符 标签。提交更改并等待该提交的 CI 完成。
2. 为通过测试的提交打标签（例如 git tag v0.1.0）并推送标签。 .github/workflows/release.yml 会拒绝版本不匹配的情况并重新运行 CI。
3. 工作流会构建六个带校验和的原生归档文件、创建 GitHub release，并发布 Linux amd64/arm64 OCI 镜像。镜像会包含 release 版本和 MCP Registry 所有权标签 io.modelcontextprotocol.server.name。
4. 首次发布时，GitHub 可能会将 GHCR 软件包设为私有。 请将其软件包设置更改为公开，然后重新运行失败的工作流作业。 工作流会在发布到注册表之前检查匿名镜像访问权限。
5. 最后一个作业会验证 server.json，并使用 GitHub Actions OIDC（id-token: write）发布，无需长期有效的注册表密钥。

注册表发布遵循官方 OCI 软件包要求 和 GitHub Actions 指南。 注册表托管的是元数据，而不是二进制文件或镜像，因此必须先公开该软件包。请勿向注册表仓库提交 PR。

OCI 软件包条目不得包含 registryBaseUrl、version 或 fileSha256；完整的注册表地址和版本应放在 identifier 中。发布器的 validate 命令不会执行 publish 执行的所有软件包专属检查，因此 smoke 测试套件也会检查这些约束。

如需在仅修正元数据后重试注册表发布，而不移动 release 标签或重新构建工件，请推送修正并触发仅发布注册表的工作流：gh workflow run publish-mcp.yml --ref main。它会检查现有的公开镜像并使用 OIDC，与由标签触发的发布相同。

在 Actions 之外发布到注册表：

mcp-publisher validate server.json
mcp-publisher login github
mcp-publisher publish server.json
curl --fail --get 'https://registry.modelcontextprotocol.io/v0.1/servers' \
  --data-urlencode 'search=io.github.ogormans-deptstack/opentofu-test'

请以 ogormans-deptstack（或已获授权的命名空间所有者）身份进行身份验证，不要使用无关的 GitHub 账户。若要在本地构建原生归档文件但不发布： bash scripts/build-release.sh 0.1.0。

许可证

MIT — 参见 LICENSE。