opentofu-test-mcp

An MCP server for the OpenTofu / Terraform native test framework (.tftest.hcl / .tfmock.hcl).

LLM agents are good at writing Terraform but routinely produce broken run, assert, and mock_provider blocks because the test-framework grammar is small but unforgiving. This server gives an agent the exact block reference, scaffolds tests from a module's real variables and outputs, generates mock providers from the installed provider schema, validates test files statically, and runs the suite — so the agent can author and check tests without guessing.

It drives the tofu CLI when present and falls back to terraform.

Tools

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

Install

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

Requires tofu (preferred) or terraform on PATH for the schema- and run-backed tools. tf_explain_test_schema and tf_validate_test work without either.

Prebuilt binaries for macOS, Linux, and Windows (amd64/arm64) are distributed with checksums on GitHub Releases. Native binaries still need a separately installed OpenTofu or Terraform CLI.

Container

The release workflow publishes an image with OpenTofu included:

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

Use -i, not -t: stdio must remain an unmodified JSON-RPC stream. Module paths passed to tools must be container paths, such as /workspace, not host paths. Only mount modules you trust: native tests can apply real infrastructure and execute provider code. The image does not inherit host cloud credentials.

Configure (client)

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

For Docker, configure command as docker and args as ["run", "--rm", "-i", "-v", "/absolute/module/path:/workspace", "ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0"].

Example

Ask the agent to "scaffold a test for this module and run it":

1. tf_scaffold_test { "dir": "." } → a .tftest.hcl skeleton.

2. tf_gen_mock_provider { "dir": "." } → mock_provider blocks (module must be initialized).

3. tf_validate_test { "path": "main.tftest.hcl" } → structural problems, if any.

4. tf_run_tests { "dir": "." } → passed=1 failed=0 errored=0 skipped=0.

Development

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

Automated MCP checks with Inspector

Requires Node.js 22.19+, Go, and OpenTofu 1.13.1 on PATH. Inspector is pinned in package-lock.json; Node is development tooling, not a server runtime dependency.

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

This launches the built server through the Inspector CLI over real stdio. It checks initialization, the exact five-tool inventory, portable input schemas (tools/list --strict), structured output, all five tools, a missing-input error, and both passing and deliberately failing native tests. Fixtures use OpenTofu's built-in terraform_data provider, so no cloud credentials or provider downloads are needed. The failing fixture is intentional. Tests work in a temporary copy and use an in-memory Inspector secret store.

To check the container with the same suite:

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

To check another build, set MCP_SERVER=/absolute/path/to/opentofu-test-mcp. CI runs both native and container smoke tests in addition to Go race tests.

For individual checks or interactive debugging:

# 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

Before contributing an MCP change, reproduce the behavior using a disposable fixture, add assertions for the regression and its error path, then run the Go and Inspector suites. Assert the JSON result, not just process exit status: Inspector exits 5 for isError: true and 6 for strict schema failures, but a valid tf_validate_test response with valid: false or a native test summary with failed > 0 still exits successfully. Inspector checks complement, not replace, unit tests; they do not prove semantic correctness of every Terraform expression or compatibility with every MCP client.

The Inspector documentation also describes the TUI and experimental mcpdo persistent connection client. The CLI is sufficient for this server's stateless requests; use a persistent client for future session-dependent flows. The pinned CLI defaults to the legacy protocol era, matching the server SDK; do not force modern-era negotiation without upgrading and testing the server first. Keep the web UI's default loopback binding and authentication enabled, and do not put secrets in fixture files or captured transcripts.

Releasing

1. Update server.json's top-level version and OCI identifier tag together. Commit the changes and wait for CI on that commit.

2. Tag that tested commit (for example git tag v0.1.0) and push the tag. .github/workflows/release.yml refuses mismatched versions and reruns CI.

3. The workflow builds six native archives with checksums, creates a GitHub release, and publishes a Linux amd64/arm64 OCI image. The image embeds the release version and the MCP Registry ownership label io.modelcontextprotocol.server.name.

4. On the first release, GitHub may create the GHCR package as private. Change its package settings to public, then rerun failed workflow jobs. The workflow checks anonymous image access before registry publication.

5. The final job validates server.json and publishes it using GitHub Actions OIDC (id-token: write), without a long-lived registry secret.

Registry publishing follows the official OCI package requirements and GitHub Actions guide. The registry hosts metadata, not the binary or image, so the package must be publicly available first. Do not submit a PR to the registry repository.

OCI package entries must not contain registryBaseUrl, version, or fileSha256; the full registry and version belong in identifier. The publisher's validate command does not perform every package-specific check that publish does, so the smoke suite checks those constraints too.

To retry registry publication after a metadata-only correction without moving the release tag or rebuilding artifacts, push the correction and dispatch the registry-only workflow: gh workflow run publish-mcp.yml --ref main. It checks the existing public image and uses OIDC, just like the tag-triggered release.

For registry publication outside 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'

Authenticate as ogormans-deptstack (or an authorized namespace owner), not an unrelated GitHub account. To build native archives locally without publishing: bash scripts/build-release.sh 0.1.0.

License

MIT — see LICENSE.