OpenTofu Test

opentofu-test-mcp

OpenTofu / Terraform ネイティブテストフレームワーク（.tftest.hcl / .tfmock.hcl）用のMCP サーバーです。

LLM エージェントは Terraform の作成を得意としていますが、テストフレームワークの文法は簡潔でありながら厳密なため、run、assert、mock_provider ブロックの作成で頻繁に問題が発生します。このサーバーを使うと、エージェントはブロックの正確なリファレンスを確認し、モジュールの実際の変数と出力からテストのひな形を作成し、インストール済みプロバイダーのスキーマからモックプロバイダーを生成し、テストファイルを静的に検証して、テストスイートを実行できます。そのため、エージェントは推測せずにテストを作成して確認できます。

tofu CLI が存在する場合はそれを使用し、存在しない場合は terraform にフォールバックします。

ツール

ツール	説明
tf_explain_test_schema	テストフレームワークのブロック（run、assert、mock_provider、expect_failures など）のリファレンスと例を返します。トピックを空にすると概要を返します。CLI は不要です。
tf_scaffold_test	モジュールの変数と出力を読み取り、run ブロック、出力ごとのアサーション、必須変数用のプレースホルダーを含む .tftest.hcl のスターターを生成します。
tf_gen_mock_provider	初期化済みのモジュールで providers schema -json を実行し、計算属性のデフォルト値があらかじめ入力された mock_resource を含む mock_provider ブロックを出力します。
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

スキーマと実行に依存するツールを使うには、tofu（推奨）または terraform が PATH 上に必要です。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

-t ではなく -i を使用してください。stdio は変更されていない 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"] に設定してください。

例

エージェントに「このモジュールのテストをひな形から作成して実行して」と依頼します。

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

これにより、ビルド済みサーバーを実際の stdio 経由で Inspector CLIから起動します。 初期化、正確な 5 つのツールの一覧、移植可能な入力スキーマ（tools/list --strict）、 構造化出力、5 つすべてのツール、入力不足エラー、成功するネイティブテストと 意図的に失敗させるネイティブテストの両方をチェックします。フィクスチャでは 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 で終了しますが、valid: false を含む 有効な tf_validate_test の応答や、failed > 0 を含むネイティブテストの概要でも、終了は 成功します。Inspector のチェックはユニットテストを補完するものであり、置き換えるものでは ありません。すべての Terraform 式の意味的な正しさや、すべての MCP クライアントとの互換性を 証明するものではありません。

Inspector のドキュメントには、 TUI と実験的な mcpdo 永続接続クライアントについても記載されています。このサーバーの ステートレスなリクエストには CLI で十分です。今後、セッションに依存するフローでは永続 クライアントを使用してください。固定されている CLI は、サーバー SDK に合わせて旧プロトコル 時代をデフォルトにしています。サーバーを先にアップグレードしてテストせずに、現代の時代の ネゴシエーションを強制しないでください。ウェブ UI のデフォルトのループバックバインドと 認証を有効に保ち、フィクスチャファイルや取得したトランスクリプトにシークレットを含めないで ください。

リリース

1. server.json のトップレベルのバージョンと OCI 識別子のタグをまとめて更新します。変更をコミットし、そのコミットの CI が完了するまで待ちます。
2. テスト済みのコミットにタグを付け（例：git tag v0.1.0）、タグをプッシュします。.github/workflows/release.yml はバージョンの不一致を拒否し、CI を再実行します。
3. このワークフローは、チェックサム付きのネイティブアーカイブを 6 種類ビルドし、GitHub リリースを作成して、Linux amd64／arm64 用の OCI イメージを公開します。イメージにはリリースバージョンと 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 が行うパッケージ固有のチェックをすべて実行するわけではないため、スモークテストでもこれらの制約を確認します。

リリースタグを動かしたりアーティファクトを再ビルドしたりせずに、メタデータのみの修正後にレジストリへの公開を再試行するには、修正をプッシュして、レジストリ専用ワークフローをディスパッチします：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'

無関係な GitHub アカウントではなく、ogormans-deptstack（または認可された名前空間の所有者）として認証してください。公開せずにネイティブアーカイブをローカルでビルドするには、次を実行します：bash scripts/build-release.sh 0.1.0。

ライセンス

MIT — 詳細はLICENSEをご覧ください。