OPA MCP

OPA MCP サーバー

Model Context Protocol（MCP）サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Zed など）を、本格的なOpen Policy Agentおよび Rego の作成環境に変えます。

+--------------------+ MCP/stdio  +-----------------+ spawn/HTTP +---------------------+
|  Claude · Cursor · |----------> | @orygn/opa-mcp  |----------> | opa · regal         |
|   VS Code · ...    |<---------- |                 |<---------- | conftest · REST API  |
+--------------------+  52 tools  +-----------------+            +---------------------+

ステータス： v0.9.1。ツールの仕様、エラーコード、環境変数には、v0.1.0 以降、SemVerに準拠したバージョニングを適用しています。

0.9.0 へのアップグレード： ツールが宣言していない引数を渡すと、ツールはそれを拒否し、エラーにその引数名を含めるようになりました。以前は無視されていました。コンパイルできないポリシーまたはクエリは、opa を実行するすべてのツールで INVALID_REGO になります。以前は一部のツールが EVAL_ERROR を返していました。rego_explain_decision は、OPA の生イベントではなく、トレースを読みやすい行として返します。conftest_test は、評価されたルールがない実行を passed: false として報告します。また、rego_generate_test_skeleton は todo_test_ スタブを書き込みます。これらは内容が記入されるまで opa test でスキップされます。レスポンスはコンパクトな JSON です。

0.8.0 へのアップグレード： opa_exec は dataPaths を opa eval --data と同様に読み込むため、テスト用フィクスチャも含むディレクトリや、データではない JSON および YAML が読み込みエラーになる場合があります。以前と同じように読み込むには、bundle として渡してください。読み込めないポリシーは、opa_exec と conftest ツールで INVALID_REGO になります。以前は EVAL_ERROR および UNKNOWN_ERROR でした。

0.7.0 へのアップグレード： Node.js 22 以降が必要です。バンドルされている OPA は 1.21 で、YAML を 1.2 スキーマに従って読み込みます。データファイル内の引用符で囲まれていない yes、no、on、off は、ブール値ではなく文字列として扱われます。OPA_BINARY または PATH を使って独自のバイナリを指定する場合、適用されるのは Node.js の要件のみです。

0.6.0 へのアップグレード： rego_bench は iterations、nsPerOp、allocsPerOp、bytesPerOp を報告するようになりました。opa が出力するフィールド（N、T、Bytes、MemAllocs、MemBytes、Extra）は、以前はトップレベルにありましたが、単一実行の場合は raw の下に移動しました。そのため、これらをトップレベルから読み取っていたものは、raw を参照する必要があります。count が 1 を超える場合、raw は省略されます。各ドキュメントは runs に格納され、fastest はトップレベルの数値の元になった実行をインデックスで示します。

0.4.0 へのアップグレード： サブプロセスはサーバーの環境を継承しなくなりました。opa.runtime().env を通じて変数を読み取るポリシーから、その変数が見えなくなります。本当に必要な場合は、変数名を OPA_MCP_PASSTHROUGH_ENV に指定してください。その理由については、セキュリティのセクションを参照してください。

0.3.0 へのアップグレード： バンドルされている OPA は 1.19 になったため、Rego v0 ポリシーは解析されなくなりました（ルール本体の前に if、部分集合の前に contains が必要です）。rego_migrate_v1 を実行して変換するか、v0Compatible: true を渡してそのまま読み込んでください。OPA_BINARY または PATH を使って独自のバイナリを指定する場合、変更はありません。

---

目次

• できること
• この MCP を選ぶ理由
• インストール
• 設定
• ツールリファレンス
• プロンプト
• リソース
• クックブック
• アーキテクチャ
• セキュリティ
• トラブルシューティング
• 開発
• バージョン管理とサポート
• ライセンス

できること

MCP クライアントが接続されると、エージェントは次のことができます。

• Rego を作成する。 ポリシーを生成、整形、リファクタリングします。サーバーは実際の opa fmt と opa parse を実行するため、出力はコマンドラインで得られるものとバイト単位で一致します。また、regal（任意）が慣用的な記述方法を提案します。
• データに対して評価する。 ポリシーと入力ドキュメントに対してクエリを実行します。任意の --explain、--profile、--coverage フラグを指定すると、実行トレース、処理負荷の高いルール、行ごとのカバレッジが表示されます。
• 拒否の理由をデバッグする。 rego_explain_decision は、エージェントが発火したルール（および発火しなかったルール）をすべて確認できるように案内するため、トレースを手作業で読むことなく「なぜ拒否されたのか」に回答できます。
• 実行中の OPA でポリシーを管理する。 REST API 経由で OPA サーバー上のポリシーを一覧表示、取得、登録、削除します。ローカルの opa run --server でも、ベアラートークン認証を使う本番環境へのデプロイでも動作します。
• バンドルをビルドして署名する。 ポリシーのディレクトリをデプロイ可能なバンドルにパッケージ化し、必要に応じて署名します。出力は通常の .tar.gz で、エージェントからデリバリーシステムに渡せます。
• Lint を実行する。 rego_lint はディレクトリまたは単一ファイルに対して Regal を実行し、各指摘事項をカテゴリ、レベル、場所とともに返します。

一般的なセッションの手順については、クックブックをご覧ください。

この MCP を選ぶ理由

OPA にはすでに優れた CLI と REST API があります。それでは、なぜ MCP ラッパーが必要なのでしょうか？

• スキーマに基づくツールインターフェース。 rego_eval を呼び出すエージェントは、検証済みの入力スキーマ、構造化された出力エンベロープ、安定したエラーコードを利用できます。そのため、自由形式の CLI テキストを解析して独自のエラー分類を考案する必要がありません。これだけでも、言語サーバーによって言語が IDE で利用可能になるのと同じように、エージェントが Rego を利用できるようになります。
• より高水準のヘルパー。 rego_explain_decision、rego_generate_test_skeleton、rego_describe_policy、rego_suggest_fix は、低水準のプリミティブを組み合わせて、エージェントが実際に依頼されるタスクを実行します。これらは OPA CLI にはありません。
• 厳選されたナレッジ。 同梱の MCP リソースでは、OPA の組み込み関数カタログ、LLM 向けに整形された公式 Rego スタイルガイド、RBAC、ABAC、Kubernetes のアドミッション、IaC ゲート、API 認可、レート制限を扱う厳選されたパターンライブラリを利用できます。そのため、エージェントは情報をスクレイピングしなくても、信頼できるコンテキストを得られます。
• エージェントが信頼できる安全境界。 パスの許可リスト、サブプロセスのタイムアウト、レスポンスサイズの上限を備えています。デフォルト設定は保守的で、サーバーを実行しても、オペレーターが意図した以上にエージェントのアクセス範囲がひそかに広がることはありません。

エージェントが opa eval の引数の順序に苦労する様子を見たことがある方なら、この MCP が解決する課題をご理解いただけるでしょう。

インストール

サーバーは stdio 経由でローカルに実行されます。クライアントに合ったインストール方法を選んでください。

Claude Desktop

claude_desktop_config.json を直接編集するか、examples/claude-desktop.json からコピーしてください。

{
  "mcpServers": {
    "opa": {
      "command": "npx",
      "args": ["-y", "@orygn/opa-mcp"],
      "env": {
        "OPA_BINARY": "/usr/local/bin/opa",
        "REGAL_BINARY": "/usr/local/bin/regal",
        "OPA_URL": "http://localhost:8181",
        "OPA_MCP_ALLOWED_PATHS": "/path/to/your/policies"
      }
    }
  }
}

/usr/local/bin/... のパスを実際のパスに置き換えてください。以下の初回インストール時の注意点をご覧ください。Windows ユーザーは C:\\path\\to\\opa.exe に置き換えてください。

または、最新リリースから opa-mcp.mcpb をダウンロードし、ダブルクリックしてください。

Claude Code（CLI）

現在のプロジェクトにサーバーを登録するには、claude mcp add を実行します。

claude mcp add \
  --env OPA_BINARY=/usr/local/bin/opa \
  --env REGAL_BINARY=/usr/local/bin/regal \
  --env OPA_MCP_ALLOWED_PATHS=/path/to/your/policies \
  opa -- npx -y @orygn/opa-mcp

これにより、設定がプロジェクトのルートにある .mcp.json に書き込まれ、そのディレクトリでの claude セッションごとに自動で読み込まれます。 グローバルに登録するには、--scope user を追加します。

パスは実際の絶対パスに置き換えてください（前述の Claude Desktop と同じ注意事項があります）。 Windows では C:\path\to\opa.exe の形式を使用します。

ポリシーリポジトリでの永続的なコンテキストと自動チェック。 OPA ポリシーリポジトリを定期的に扱う場合、2 つのファイルを追加すると、セッションごとに繰り返していた設定が不要になります。

• examples/CLAUDE.md -- リポジトリのルート、または .claude/CLAUDE.md にコピーします。 Claude Code はこれを毎回のセッションで読み込むため、エージェントは使用するツールと適用される規約を常に把握できます。
• examples/claude-code-hook.json -- hooks ブロックを .claude/settings.json にマージします。Claude が .rego ファイルを書き込むか編集した後に opa check を実行し、エラーがあれば手動でツールを呼び出すことなく Claude に返します。

Cursor

examples/cursor.json を .cursor/mcp.json（プロジェクト単位）または ~/.cursor/mcp.json（ユーザー単位）に配置します。

VS Code（GitHub Copilot Chat）

examples/vscode.json を .vscode/mcp.json に配置するか、servers ブロックをユーザーの settings.json にある mcp.servers の下に貼り付けます。

Windsurf、Zed など

配置してすぐに使える設定一式については、examples/ を参照してください。

手動インストール（任意の MCP クライアント）

npm install -g @orygn/opa-mcp
opa-mcp --version

次に、クライアントが opa-mcp バイナリを参照するように設定します。

Docker

docker pull orygn/opa-mcp:latest
docker run --rm -i \
  -v /path/to/your/policies:/policies:ro \
  -e OPA_MCP_ALLOWED_PATHS=/policies \
  orygn/opa-mcp

このイメージはマルチアーキテクチャ（linux/amd64、linux/arm64）に対応し、固定バージョンの opa と regal が含まれており、root 以外のユーザーとして実行されます。ホストに OPA や Regal をインストールする必要はありません。

⚠ すべてのツール呼び出しで OPA_BINARY_NOT_FOUND が返される場合

npm パッケージには、ビルド対象の 5 つのプラットフォーム用に opa が含まれているため、クライアントの PATH に opa がなくても問題ありません。MCPB には同梱されておらず、その他のプラットフォームでは npm にも同梱されていません。その場合、サーバーは起動しますが、すべてのツール呼び出しで OPA_BINARY_NOT_FOUND が返されます。npm パッケージにも MCPB にも regal や conftest は同梱されておらず、Docker イメージには regal は含まれていますが conftest は含まれていません。そのため、どちらの場合も、それらのツールには PATH のエントリか明示的なパスが必要です。

解決方法： 各バイナリへの絶対パスを指定した OPA_BINARY と REGAL_BINARY の環境変数を、クライアント設定に追加します。examples/ にある設定例には、置き換えが必要なプレースホルダーパスが記載されています。 実際のパスは次のコマンドで確認できます。

which opa && which regal                                    # macOS / Linux

Get-Command opa, regal | Select-Object Source              # Windows

この問題は、イメージに opa と regal が含まれ、PATH を完全に介さない Docker インストールには影響しません。MCPB バンドルにはどちらも含まれておらず、npm インストールのような同梱バイナリへのフォールバックもありません。OPA_BINARY を設定するか、opa を PATH に追加してください。 詳しくはトラブルシューティングを参照してください。

設定

サーバーは環境変数から設定を読み込みます。すべての変数は省略可能で、http://localhost:8181 で動作するローカル OPA 向けの適切なデフォルト値が設定されています。

変数	デフォルト	用途
OPA_URL	http://localhost:8181	opa_* ツールで使用する、OPA REST エンドポイントのベース URL です。
OPA_TOKEN	(未設定)	インスタンスで認証が必要な場合に使用する、OPA のベアラートークンです。シークレットとして扱われます。ログやツールの応答に出力されることはありません。
OPA_BINARY	opa (on PATH)	rego_* ツールで使用する opa CLI のパスです。
REGAL_BINARY	regal (on PATH)	regal リンターのパスです。rego_lint、rego_fix、rego_security_audit に必要です。
CONFTEST_BINARY	conftest (on PATH)	conftest バイナリのパスです。conftest_* ツールでのみ必要です。見つからない場合は CONFTEST_NOT_FOUND を返します。
OPA_MCP_ALLOWED_PATHS	(未設定)	サーバーがポリシーを読み込めるディレクトリを、カンマまたはセミコロンで区切って指定します。未設定の場合、ファイルベースのツールはディスクからの読み込みを拒否します。
OPA_MCP_LOG_FILE	<tmpdir>/orygn-opa-mcp.log	サーバーがログを書き込むファイルのパスです。サーバーは標準出力には書き込みません。このチャネルは MCP プロトコル専用です。
OPA_MCP_LOG_LEVEL	info	debug、info、warn、error のいずれかです。
OPA_MCP_MAX_RESPONSE_BYTES	100000	1 回のツール応答に対する上限です。上限を超えるペイロードは、__truncated: true マーカーを付けて切り詰められます。512 未満の値は拒否されます。
OPA_MCP_TIMEOUT_MS	30000	起動されたサブプロセス（opa、regal）に対するハードタイムアウトです。タイムアウト後、子プロセスに SIGTERM を送信し、その後 SIGKILL を送信します。
OPA_MCP_HTTP_TIMEOUT_MS	15000	OPA REST API への各リクエストのタイムアウトです。接続の試行から応答の最後のバイトを受信するまでを対象とし、タイムアウト時は TIMEOUT として報告されます。
OPA_MCP_NO_TELEMETRY	(未設定)	匿名の起動時 ping を無効にするには 1 を設定します。ping では、サーバーのバージョン、OS プラットフォーム、ランダムなインストール ID が送信されます。インストール ID は ~/.orygn/opa-mcp/install-id に保存されます。コンテナーと CI ジョブでは、代わりに container または ci ラベルが送信されます。ポリシーの内容やファイルパスが送信されることはありません。
OPA_MCP_MAX_SUBPROCESS_BYTES	33554432 (32 MiB)	サブプロセスの標準出力と標準エラーから取得する最大バイト数です。これらは個別にカウントされます。上限を超えると、ストリームが制限され、子プロセスが停止され、ツールは OUTPUT_TOO_LARGE を返します。これは、出力がすでにメモリ上にある状態で応答を切り詰める OPA_MCP_MAX_RESPONSE_BYTES とは異なります。
OPA_MCP_PASSTHROUGH_ENV	(未設定)	opa、regal、conftest に渡す環境変数名をカンマ区切りで指定します。それ以外の環境変数は渡されません。ここで指定した値は、サーバーが評価するすべてのポリシーから opa.runtime().env を通じて読み取れます。この位置で参照されても安全な値に限って使用してください。
OPA_MCP_BLOCK_ENV	(未設定)	組み込みの許可リストに含まれていても、opa、regal、conftest に渡さない環境変数名をカンマ区切りで指定します。最後に適用されるため、OPA_MCP_PASSTHROUGH_ENV の指定も上書きします。認証情報を含む可能性があるプロキシ変数を除外するために使用できますが、プロキシは利用できなくなります。
OPA_MCP_ALLOWED_PATHS 内のパスは絶対パスである必要があります。また、*_BINARY の値には、PATH から検索されるコマンド名、または絶対パスを指定してください。それ以外の場合、サーバーは起動時に停止します。実行できないバイナリは、各ツール呼び出しで構造化エラーとして報告されます。

ツールのリファレンス

すべてのツールは JSON エンベロープを返します。

{ "ok": true, "data": { ... }, "warnings": [ ... ] }
{ "ok": false, "error": { "code": "INVALID_REGO", "message": "...", "hint": "...", "details": { ... } } }

安定したエラーコード：INVALID_INPUT、INVALID_REGO、INVALID_BUNDLE、EVAL_ERROR、OPA_BINARY_NOT_FOUND、REGAL_NOT_FOUND、CONFTEST_NOT_FOUND、OPA_UNREACHABLE、OPA_AUTH_FAILED、POLICY_NOT_FOUND、DATA_NOT_FOUND、PATH_NOT_ALLOWED、PATH_NOT_FOUND、NO_TESTS_FOUND、COVERAGE_BELOW_THRESHOLD、OPA_VERSION_UNSUPPORTED、GITHUB_TOKEN_MISSING、GIST_CREATE_FAILED、OUTPUT_TOO_LARGE、SUBPROCESS_KILLED、OPA_URL_INVALID、TIMEOUT、CANCELLED、UNKNOWN_ERROR。rego_eval のバッチでは、別の入力がタイムアウトした後、処理が到達する前に呼び出しが停止した入力に対して、NOT_EVALUATED が返されることもあります。

カテゴリ A：作成と静的解析

実行中の OPA サーバーを必要とせずに、Rego のソースコードを操作します。opa fmt、opa parse、opa check、opa inspect、opa capabilities、opa deps、regal をラップします。

ツール	機能
rego_format	Rego ソースをフォーマットします。opa fmt をラップしています。べき等です。
rego_check	Rego の型チェックと検証を行います。opa check をラップしています。
rego_lint	ファイルまたはディレクトリに対して Regal を実行します。各違反について、カテゴリ、レベル、場所を返します。PATH に regal があるか、REGAL_BINARY が設定されている必要があります。
rego_parse_ast	Rego を AST JSON に解析します。opa parse をラップしています。
rego_inspect	バンドルまたはディレクトリを調査し、パッケージ、ルール、アノテーションを確認します。opa inspect をラップしています。
rego_capabilities	解決された opa バイナリ（OPA_BINARY、次に PATH、最後に同梱コピー）の対応する組み込み関数と機能を一覧表示します。完全なレコードを返す builtins の名前は最大 100 個です
rego_deps	静的な依存関係分析を行います。ルールレベルのデータ参照と、パッケージ間の呼び出しを確認します。
rego_migrate_v1	Rego v0 ソースを v1 に移行します。v1 で予約されているルール名（contains、every、if、in）を変更し、v1 で削除された組み込み関数を正確な同等のものに置き換えた後、opa fmt --rego-v1 で構文を変換し、opa check で検証します。inputs を指定すると、それぞれについて元のコードを v0 として、移行後のコードを v1 として評価し、差異のあるルールを報告します。また、関数の比較に使用する queries も評価します。{ original, migrated, changed, valid, errors, rewrites, notes, equivalence } を返します。dataPaths を指定すると、その比較に必要なポリシーが読み取るデータを読み込みます。
rego_check_schema	JSON Schema に照らして Rego を検査します。ポリシーが読み取るすべての input.* フィールドがスキーマに存在することを、opa check --schema を使って検証します。インラインスキーマ、JSON Schema ファイルのパス、またはポリシーに schemas: アノテーションがある場合はスキーマディレクトリを指定できます。

おすすめ：rego_format

// Input
{
  "source": "package x\nallow if input.user==\"admin\""
}

// Output (ok)
{
  "ok": true,
  "data": {
    "formatted": "package x\n\nallow if input.user == \"admin\"\n",
    "changed": true
  }
}

おすすめ：rego_check

// Input
{
  "source": "package x\nallow if y",
  "strict": true
}

// Output (error path; the JSON diagnostics arrive on stderr from opa)
{
  "ok": true,
  "data": {
    "valid": false,
    "errors": [
      {
        "code": "rego_unsafe_var_error",
        "message": "var y is unsafe",
        "location": { "row": 2, "col": 11 }
      }
    ]
  }
}

カテゴリー B：評価とテスト

ポリシーと入力に対してクエリを実行します。opa eval、opa test、opa bench をラップします。これらの各ツールでは v0Compatible を指定すると、OPA 1.0 より前に記述されたポリシーを移行せずに読み込めます。また、rego_check から rego_verify、conftest_test に至るまで、opa または conftest を通じてポリシーを読み込むほかのすべてのツールでも同様です。その場合、OPA はクエリも v0 として読み込むため、将来のキーワードがインポートされ、in と every は引き続き使用できます。rego_policy_diff では、旧形式のポリシーと移行後のコピーを比較するため、サイドごとに指定します（v0CompatibleA、v0CompatibleB）。例外は、opa deps にそのようなオプションがないため rego_deps と、どちらのバージョンも読み込めるため Regal ツールです。

ツール	機能
rego_eval	ポリシーと入力に対してクエリを評価します。基本となるツールです。inputs を指定すると、1 回の呼び出しで最大 50 件の入力ドキュメントに対してクエリを評価し、それぞれの結果を報告します。ポリシーを指定しない場合は、クエリのみで組み込みの式または任意の式を試せます。各結果にはクエリが defined かどうかが示され、print() の出力は printed で返されます。
rego_eval_with_explain	--explain=full を指定して評価し、OPA の生のトレースイベントを返します。rego_explain_decision は同じトレースを読みやすい行として表示します。
rego_eval_with_profile	--profile を指定して評価し、ルールごとの実行時間と評価回数を返します。
rego_eval_with_coverage	--coverage を指定して評価し、行ごとのカバレッジを返します。
rego_test	opa test で Rego のユニットテストを実行します。成功、失敗、スキップ、エラーの件数と、テストごとの記録を返します。errored は OPA が評価できなかったテストの数です。テストの失敗やエラーがなければ、coverage または threshold を指定するとカバレッジレポートも追加されます。allPassed が true になるのは、少なくとも 1 件のテストが実行され、失敗、エラー、スキップがいずれもなかった場合のみです。
rego_bench	opa bench を実行し、統計的な実行時間データを返します。
rego_compile_query	ポリシーに対してクエリを部分評価します。
opa_exec	複数の入力ファイルに対して判定を一括評価します。ファイルごとの結果とともに、successCount と errorCount を返します。dataPaths は opa eval --data と同様に読み込まれ、bundle にはバンドルを指定します。
rego_test_multiroot	ルートごとに opa test を実行し、結果を集計します。opa test . でパッケージの競合が発生する場合に使用します。合計には totalErrored が含まれます。

注目：rego_eval

// Input
{
  "query": "data.rbac.allow",
  "source": "package rbac\nimport rego.v1\nallow if input.role == \"admin\"",
  "input": { "role": "admin" }
}

// Output
{
  "ok": true,
  "data": {
    "result": [{ "expressions": [{ "value": true, "text": "data.rbac.allow", "location": { "row": 1, "col": 1 } }] }]
  }
}

カテゴリー C：バンドル操作

デプロイ可能なバンドルをパッケージ化、署名、検証します。opa build、opa sign、opa build --verification-key をラップします。

ツール	機能
opa_bundle_build	ポリシーディレクトリから .tar.gz バンドルをビルドします。optimize と revision に対応しています。
opa_bundle_sign	秘密鍵を使用してバンドルディレクトリに署名します。アーカイブは拒否されます。OPA はアーカイブ内から署名を読み取り、署名は opa_bundle_build によって付与されるためです。ディレクトリの署名は、同じ名前であれば配置場所を問わず有効です。パス、アルゴリズム、ファイル数を返します。
opa_bundle_verify	opa build --verification-key を使用して公開鍵で署名済みバンドルを検証します。失敗時には、理由として、鍵の不一致、スコープの不一致、変更、追加、欠落、解析不能なファイル、未署名、またはバンドルの読み込み失敗が示されます。

カテゴリ D：OPA サーバーの管理

稼働中の OPA サーバーと REST API を介して通信します。到達可能なサーバーを指すように OPA_URL を設定する必要があります。

ツール	説明
opa_list_policies	サーバーに登録されているポリシー ID を件数とともに一覧表示します。includeSource と includeAst を指定すると、Rego テキストまたは解析済み AST が追加されます。
opa_get_policy	ID を指定して単一のポリシーを取得します。Rego ソースを返します。includeAst を指定すると、OPA の解析済み AST が追加されます。
opa_put_policy	ポリシーをアップロードまたは置換します。既存のポリシーがあったかどうかは replaced で示されます。コンパイルできないポリシーの場合は、OPA のエラーとともに INVALID_REGO が返され、保存されません。
opa_delete_policy	ID を指定してポリシーを削除します。
opa_get_data	データ階層からパスを読み取ります。
opa_put_data	データ階層のパスに書き込みます。
opa_patch_data	データ階層に JSON Patch を適用します。
opa_delete_data	データ階層からドキュメントを削除します。
opa_query_decision	入力とともに /v1/data/... 判定エンドポイントに POST します。defined: false はパスが値を生成しなかったことを意味し、false と同じではありません。
opa_compile_query	稼働中のサーバーに対してクエリを部分評価します。
opa_health	生存確認／準備状態の確認です。応答するサーバーは、OPA の理由とともに healthy: true または healthy: false を返します。OPA_UNREACHABLE はサーバーにまったく到達できなかったことを意味します。
opa_status	status キーの下に、opa_config と同じ GET /v1/config ドキュメントを返します。バンドルおよび判定ログの状態（/v1/status）は公開されません。サービスヘッダーの値は伏せられます。
opa_config	GET /v1/config からサーバー設定を取得します。OPA は credentials ブロックを削除しますが、サービスヘッダーはそのまま返すため、ここではヘッダーの値を伏せて名前を保持します。

カテゴリ E：高レベルのヘルパー

差別化を図る機能群です。エージェントが実際に依頼されるタスクに合わせて、低レベルのプリミティブを組み合わせます。

ツール	機能
rego_explain_decision	完全なトレース付きで評価し、実行されたルールと条件を満たしたルール、および読みやすい行形式のトレースを返します。Fail 行には、ルールを停止させた条件が示されます。
rego_generate_test_skeleton	ポリシーを指定すると、ルールごとにスタブを1つ含む _test.rego のスケルトンを生成します。スタブは todo_test_ ルールで、実装して test_ に名前を変更するまでは opa test によってスキップとして報告されます。
rego_describe_policy	AST から、ポリシーのパッケージ、インポート、およびルールごとの構造を要約します。ポリシーが読み取る入力の参照については、rego_infer_input_schema を使用してください。
rego_suggest_fix	rego_check の errors または rego_lint の violations を変更せずに渡すと、診断ごとに信頼度レベル付きの修正案と、該当する場合はルールのドキュメントへのリンクを返します。
rego_coverage_gaps	opa test --coverage を実行し、ファイルごとの未カバー行の範囲を、カバー率が低い順に返します。目標の割合を下回るファイルに絞り込むには、threshold を使用します。
rego_security_audit	ディレクトリ全体を対象に、bugs カテゴリに限定した regal lint と、security カテゴリに属するカスタムルールを実行します。重大度別に分類した指摘事項と、修正方法のガイダンスを返します。解析できないモジュールは unparseable に一覧表示され、残りのモジュールは監査されます。
rego_infer_input_schema	opa parse を使ってポリシー（またはポリシーのディレクトリ）を静的に解析し、ポリシーが読み取るすべての input.* フィールドを記述した JSON Schema を返します。入力の一部にバインドされたループ変数、ルール、関数パラメーターを追跡するため、some c in input.containers の後に c.image がある場合は input.containers[].image となります。型が設定されるのは、ポリシーによって示されている場合のみです。OPA の実行は不要です。テスト入力や rego_check_schema のスキーマを作る出発点として使えますが、まず内容を確認してください。
rego_fix	regal fix を実行して、機械的な修正を自動適用します。Regal 0.42 以降では、opa-fmt、use-rego-v1、use-assignment-operator、no-whitespace-comment、directory-package-mismatch、non-raw-regex-pattern、prefer-equals-comparison、redundant-existence-check、constant-condition を修正します。旧リリースでは一部の修正に対応しています。まず変更をプレビューするには dryRun: true を使用します。適用されたルールをファイルごとにまとめて返します。また、directory-package-mismatch では、ファイルの移動先となる新しいパスも返します。
rego_format_write	opa fmt --write を実行し、1つ以上の Rego ファイルまたはディレクトリを正規形式に整えて、その場で書き換えます。ファイルを変更せず、変更対象のファイルを一覧表示するには dryRun: true を使用します。書き込み前に、すべてのファイルの解析が成功することを検証します。regoV1、v0Compatible、v1Compatible フラグに対応しています。必要なのは opa のみです。
rego_policy_diff	同じクエリを2つのポリシーに対して並列に評価し、結果を比較します。equal: true/false、各側の生の値（resultA/resultB）、および異なるドット記法／ブラケット記法の JSON パスである changedPaths を返します。各側には、インラインソースまたはファイル／ディレクトリのパスを指定できます。リファクタリング後の同等性の検証や、2つのポリシーバージョン間の差異の特定に役立ちます。inputs を指定すると、1回の呼び出しで最大50件の入力ドキュメントを使って両者を比較し、入力ごとに1つのエントリを含む batch を返します。differing は、結果が一致しない入力の数を示します。
rego_verify	SMT ソルバー（WASM 経由の Microsoft Z3）を使って、Rego ルールの性質を形式的に検証します。テストとは異なり、数学的に考えられるすべての入力をチェックし、その性質が成り立つことを証明するか、具体的な反例を返します。kind フィールドには always_true、never_true、satisfiable を指定します。等価性、比較、文字列組み込み関数（startswith、endswith、contains、regex.match）、複数節のルール、ルールのデフォルト、非ブール値のヘッド値、ルール間のインライン展開に対応しています。否定による失敗、内包表記、部分集合ルールと部分オブジェクトルール、関数、else チェーン、複雑な正規表現については、推測せずに INCONCLUSIVE を報告します。存在しないフィールドを読み取る本体は true ではなく undefined となるため、always_true では空の入力でもルールが成立する必要があります。
rego_explain_undefined	Rego クエリが undefined になる理由、デフォルトにフォールバックする理由、または（deny などの集合の場合に）要素を含まない理由を説明します。通常の eval、完全なトレース付きの eval、条件ごとの AST 解析を組み合わせ、各ルールを妨げている本体の式を特定します。各ルールでどの条件が妨げとなったかを構造化して示し、人が読みやすい要約も返します。
rego_playground_share	ポリシー（および任意の入力）を秘密の GitHub Gist として公開し（一覧表示する場合は public: true を指定）、再現例を共有するためのリンクを返します。gist スコープを持つ GITHUB_TOKEN が必要です。設定されていない場合は GITHUB_TOKEN_MISSING を返します。

カテゴリ F：Conftest（設定ポリシーのテスト）

conftest を使って、Kubernetes マニフェスト、Terraform プラン、Dockerfile、Helm チャート、およびあらゆる YAML／JSON／HCL／TOML／INI を Rego ポリシーに照らしてテストします。PATH 上に conftest があるか、CONFTEST_BINARY が設定されている必要があります。そうでない場合、4 つのツールはすべて CONFTEST_NOT_FOUND を返します。

ツール	機能
conftest_test	conftest test を使って、設定ファイルまたはインラインドキュメントを Rego ポリシーに照らして評価します。ファイルごと、名前空間ごとの結果には常に配列が含まれ、ファイル名ごとの件数を集計したサマリーも返します。パーサー名は固定の候補から選びます。ルールが評価されなかった場合（namespace が誤っている、または deny／violation／warn ルールがない場合）は、conftest 自体の終了コードが 0 でも、nothingEvaluated: true とともに passed: false として報告されます。
conftest_verify	conftest verify を使って、conftest ポリシーディレクトリ内の test_* ルールを実行します。ルールごとの結果を報告し、テストがない場合は NO_TESTS_FOUND を返します。
conftest_pull	conftest pull を使って、OCI レジストリまたは Git リポジトリからポリシーバンドルをローカルディレクトリに取得します。対象ディレクトリは存在していなくてもかまいません。conftest が作成し、最初に中身を空にするため、他のものが保存されているディレクトリは指定しないでください。policy を省略すると、conftest のデフォルトが使用されます。このデフォルトも、許可されたルートのいずれかの中にある必要があります。
conftest_push	conftest push を使って、ローカルのポリシーディレクトリを OCI アーティファクトとしてパッケージ化し、レジストリにプッシュします。レジストリの認証情報はホスト環境（docker login、ORAS キーチェーンなど）から取得され、ツールを介して渡されることはありません。

注目機能：インライン設定を使った conftest_test

// Input
{
  "inlineConfig": "apiVersion: v1\nkind: Pod\nspec:\n  containers:\n  - name: app\n    image: nginx:latest",
  "inlinePolicy": "package main\ndeny contains msg if { input.spec.containers[_].image == \"nginx:latest\"; msg := \"pin your image tag\" }"
}

// Output
{
  "ok": true,
  "data": {
    "passed": false,
    "results": [
      {
        "filename": "<inline>",
        "namespace": "main",
        "successes": 0,
        "failures": [{ "msg": "pin your image tag" }],
        "warnings": [],
        "skipped": [],
        "exceptions": []
      }
    ],
    "summary": {
      "passed": 0,
      "failed": 1,
      "warnings": 0,
      "skipped": 0,
      "successes": 0,
      "failures": 1
    }
  }
}

カテゴリ G：メタ情報

ツール	機能
mcp_server_info	サーバー名、バージョン、解決済みの opa／regal／conftest のバージョン、トランスポートの種類、Node.js のバージョンを 1 回の呼び出しで返します。エージェントがどのサーバーインスタンスに接続しているかを確認するのに便利です。

プロンプト

3 つの MCP プロンプト がサーバーに付属しています。クライアントでは、スラッシュコマンドまたはワークフローテンプレートとして表示されます。

プロンプト	目的
policy_authoring_assistant	新しいポリシーの作成をエージェントに案内します。判断対象について質問し、草案を作成、レビュー、フォーマット、リント、テストします。
policy_review_checklist	既存のポリシーをレビューするためのチェックリストです。網羅性、エッジケース、パフォーマンス、セキュリティ上の落とし穴を確認します。
decision_debugging_workflow	予期しない判断が下された場合の診断フローです。入力を収集し、explain 付きで実行し、ルールを特定して、修正案を提示します。

リソース

3 つの MCP リソース は、エージェントがいつでも参照できるように、厳選されたリファレンスデータを公開しています。

リソース URI	内容
opa://builtins	opa capabilities --current から読み込み時に取得する、カテゴリ別の OPA 組み込み関数リファレンスです。セキュリティ上機微な関数（http.send、crypto.x509.*、opa.runtime）にはフラグが付けられます。
opa://style-guide	LLM が利用しやすい形式にまとめた Rego スタイルガイドです。
opa://patterns	よくあるパターンを厳選したライブラリです。RBAC、ABAC、Kubernetes admission、IaC ゲート、API 認可、レート制限が含まれます。各パターンには使用場面、完全な Rego、テスト、よくある落とし穴が含まれます。

クックブック

このツールセットが想定して設計された、いくつかのセッション例です。

「ポリシーの作成を手伝ってください」

You: I need an authz policy: editors can read/write, viewers can only read,
     admins can do anything.

Agent: I'll draft it. (calls rego_format on a draft, then rego_check, then
       rego_lint)

Agent: (calls rego_eval with an `inputs` batch: each role, no role at all,
       a role that is not a string, an unknown method)

Agent: Here's the policy. A request with no role, or a role that is not a
       string, is denied. I kept those probes as tests next to one case per
       role. (calls rego_generate_test_skeleton, fills in the stubs, then
       rego_test)

Agent: All 9 tests pass. Want me to save it to <path>?

「なぜ拒否されたのですか？」

You: This API call is being denied and I don't know why.
     [pastes input.json]

Agent: (calls rego_explain_decision against your local policy with that input)

Agent: The deny comes from rule `forbid_anonymous_writes` at line 17.
       Specifically, `input.user` is null and the request method is "POST".
       The rule fires, which causes the default deny. To allow this, you'd
       need either an authenticated user or a policy exception for this
       endpoint.

「このポリシーをステージング OPA にプッシュしてください」

You: Push policies/rbac.rego to the staging OPA server, but first lint and
     test it.

Agent: (rego_lint → 2 style warnings, no errors)
       (rego_test on policies/ → all pass)
       (opa_put_policy with id="rbac" against $OPA_URL)
       (opa_get_policy to verify)

Agent: Done. Policy `rbac` is live on staging at $OPA_URL.

アーキテクチャ

┌──────────────────────────────────── @orygn/opa-mcp ───────────────────────────────────┐
│                                                                                       │
│   src/server.ts ──── McpServer (stdio) ─── tool / prompt / resource registries        │
│                          │                                                            │
│                          ├── tools/authoring/         ─┐                              │
│                          ├── tools/evaluation/        ─┤                              │
│                          ├── tools/bundles/           ─┼─── lib/opa-cli.ts ──┐        │
│                          ├── tools/server-management/ ─┤                     │        │
│                          ├── tools/helpers/           ─┤                     │        │
│                          ├── tools/conftest/          ─┤                     │        │
│                          ├── tools/meta/              ─┘                     │        │
│                          │                                                   ▼        │
│                          │                              lib/subprocess.ts ──┴── opa   │
│                          │                              lib/regal-cli.ts   ───── regal│
│                          │                              lib/conftest-cli.ts ─ conftest│
│                          │                              lib/opa-client.ts  ───── HTTP │
│                          │                                                            │
│                          └── lib/output.ts (envelope + truncation)                    │
│                              lib/security.ts (path allow-list)                        │
│                              lib/errors.ts (structured failures)                      │
│                              lib/logger.ts (file-only, never stdout)                  │
└───────────────────────────────────────────────────────────────────────────────────────┘

運用するうえで知っておくべきことが4つあります。

1. stdout はプロトコルの通信チャネルです。 サーバーは lib/logger.ts を介してファイルにログを記録し、stdout には一切書き込みません。stdout に余計なバイトが出力されると、クライアントは切断されます。MCP トランスポート層は厳格です。

2. ツールハンドラーは例外をスローしません。 各ハンドラーは独自に例外を捕捉し、構造化された { ok: false, error: ... } エンベロープを返すため、エージェントにはスタックトレースではなく、一貫したエラー語彙が表示されます。ツールの入力スキーマに適合しない引数はハンドラーに到達しません。MCP レイヤーがこれを拒否し、エンベロープではなく、テキストが MCP error -32602: Input validation error: で始まる isError: true のツール結果を返します。サブプロセスの出力のデコードは非同期コールバック内で行われるため、そこで例外がスローされるとハンドラーを完全に迂回してしまいます。そのため、この処理では、それを捕捉できない try／catch に任せるのではなく、バイト数で上限を設けています。

3. サブプロセスには実行時間、サイズ、環境の上限があります。 lib/subprocess.ts は shell: false でバイナリを実行し、ハードタイムアウトを設定します。タイムアウト時には SIGTERM の後に SIGKILL へ移行し、各ストリームにもバイト数の上限を設けます。エージェントがシェルコマンドを組み立てられる経路は、サーバー内に存在しません。タイムアウトだけでは不十分です。opa は結果をメモリにバッファリングし、終了時にまとめて書き出すため、タイムアウトよりはるかに早く完了するコマンドでも、数百メガバイトを送信することがあります。

4. 子プロセスはサーバーの環境を継承しません。 代わりに lib/child-env.ts が明示的な許可リストを構成します。Rego は opa.runtime().env を介してインタープリターの環境を読み取れるため、渡されたものはすべて、サーバーが評価するあらゆるポリシーから読み取り可能です。リストに含まれるプロキシ変数も同様です。

セキュリティ

このサーバーは、ユーザー自身のマシン上で MCP クライアントが起動し、stdio 経由で通信するローカル実行を想定して設計されています。ネットワークに公開することは想定していません。

• ファイルを扱うツールは、OPA_MCP_ALLOWED_PATHS の外にあるものは読み取りません。この変数が設定されていない場合、ファイルツールは PATH_NOT_ALLOWED を返します。
• サブプロセスは shell: false、厳格なタイムアウト、および取得する出力のバイト数上限を設定して実行されます。
• 評価対象のポリシーは、サーバーの環境変数を読み取れません。 Rego は opa.runtime().env を通じて opa プロセスの環境変数を公開するため、process.env を継承した子プロセスは、評価する任意のポリシーに OPA_TOKEN、GITHUB_TOKEN、その他すべての変数を渡してしまいます。rego_eval はインラインソースを受け付けるため、そこにアクセスするのにファイルシステムは不要です。そのため、エージェントが信頼できない Rego を読み取ると、プロンプトインジェクション一つで悪用される可能性があります。子プロセスには、代わりに明示的な許可リストが渡されます（lib/child-env.ts）。このリストにはクラウドやリポジトリのトークンは含まれていませんが、認証情報が一切ないわけではありません。HTTP_PROXY とその関連変数が含まれており、プロキシ URL にユーザー名とパスワードを埋め込めるためです。これらを除外すると、企業プロキシを利用するユーザーに支障が出るため含めています。それでも除外する場合は、OPA_MCP_BLOCK_ENV に変数名を指定してください。OPA_MCP_PASSTHROUGH_ENV を指定すると、個別の変数を再び渡せるようになります。
• OPA_TOKEN がツールの応答やログに出力されることはなく、子プロセスにも渡されません。
• Rego を評価するツールには、オープンワールドかつ読み取り専用ではないことが注記されています。 rego_eval とその派生ツール、rego_test、rego_test_multiroot、rego_bench、rego_compile_query、opa_exec、rego_migrate_v1（inputs が指定された場合）、explain、diff、coverage の各ヘルパー、conftest ツール、Regal ツール（プロジェクト独自のルールを実行する rego_lint、rego_security_audit、rego_fix）はすべて Rego を実行します。また、OPA の http.send により、ポリシーは任意のネットワークアドレスにアクセスし、書き込みを行えます。ヒントに基づいて動作するクライアントは、いずれかを実行する前に確認を求めます。例外は opa_query_decision と opa_compile_query です。これらではリモート OPA がすでに保持しているポリシーを評価し、ヒントはそのサーバーに対する呼び出しの動作を示します。評価を行うツールは、capabilities ファイルを渡すことも受け取ることもできないため、評価時に http.send を制限することはできません。rego_check と opa_bundle_build は capabilities ファイルを受け付けますが、その影響はチェックとビルドに限られます。
• リリースは npm provenance を付けて公開されます。Docker イメージは、コミット済みの Dockerfile からビルドされ、固定されたバージョンの opa と regal は公開済みのダイジェストと照合されます。

脆弱性を報告するには、SECURITY.md の手順に従ってください。セキュリティ上の問題について、公開 issue を作成しないでください。

トラブルシューティング

よくある問題と、すぐにできる対処法です。

バイナリがインストールされているのに、OPA_BINARY_NOT_FOUND（または REGAL_NOT_FOUND / CONFTEST_NOT_FOUND）が表示される。 (初日に最もよくある問題です。まずはこちらをお読みください)

MCP クライアント（特に Windows および macOS の Claude Desktop）は、ユーザーのローカルの bin ディレクトリを除外した、意図的に縮小された PATH でサーバーを起動します。対話型シェルでは問題なく動作するディレクトリも除外されます。バイナリはマシン上にありますが、起動された MCP サーバーからは見えません。

opa の絶対パスを確認します。

# macOS / Linux
which opa
# → /usr/local/bin/opa  (or /opt/homebrew/bin/opa, or ~/.local/bin/opa)

# Windows
Get-Command opa | Select-Object -ExpandProperty Source
# → C:\Users\you\bin\opa.exe  (or wherever)

次に、クライアントの MCP env ブロックで、OPA_BINARY にその絶対パスを設定します。他のバイナリにも同じ原因と対処法が当てはまります。rego_lint / rego_security_audit / rego_fix で REGAL_NOT_FOUND が報告される場合や、conftest_* ツールで CONFTEST_NOT_FOUND が報告される場合は、同じ方法で REGAL_BINARY / CONFTEST_BINARY に絶対パスを設定します（which regal / which conftest で確認できます）。シェルの PATH にバイナリが含まれているだけでは不十分です。起動されたサーバーには縮小された PATH が渡されます。examples/ の設定にはこれらの環境変数がすでに含まれているので、プレースホルダーのパスを編集してください。

opa と regal が同梱され、PATH をまったく使用しない Docker インストールでは、この問題は発生しません。MCPB バンドルは OPA_BINARY または PATH から opa を解決するため、この問題が発生する可能性があります。

サーバーは起動するが、その後クライアントに「切断されました」と表示される。

最も可能性の高い原因は、MCP フレーム以外の内容をプロセスが標準出力に書き込んでいることです。カスタムツールを追加した場合は、ツールが呼び出すライブラリが標準出力に書き込んでいないか確認してください。標準出力を保護する仕組みは lib/logger.ts です。console.log ではなく、こちらを使ってください。

プロジェクト内のファイルで PATH_NOT_ALLOWED が発生する。

OPA_MCP_ALLOWED_PATHS はデフォルトでは空です。サーバーによる読み取りを許可する絶対パスを、カンマ区切りで設定してください。

opa_* ツールの呼び出し時に OPA_UNREACHABLE が発生する。

OPA_URL（デフォルトは http://localhost:8181）には、稼働中の OPA サーバー（opa run --server ...）を指定する必要があります。curl $OPA_URL/health で確認してください。

opa_* ツールの呼び出し時に TIMEOUT が発生する。

リクエストが OPA_MCP_HTTP_TIMEOUT_MS（デフォルトは 15 秒）以内に完了しませんでした。OPA の応答が遅いか、OPA_URL から応答がなく、接続が拒否されずにタイムアウトしている可能性があります。どちらの場合も、ここからは同じように見えます。OPA_URL とサーバーの負荷を確認するか、制限時間を延長してください。

インラインソースのリンティング時に directory-package-mismatch 違反が発生する。

v0.1.1 以降、インラインソースの呼び出しではサーバーがこのルールを自動的に無効にします。この違反が表示される場合は古いバージョンを使用しています。v0.1.1 以降にアップグレードしてください。このルールの正確な結果を得るには、source を直接渡すのではなく、実際のディスク上のファイルに対して paths を使ってリンティングしてください。

ログはどこにありますか？

デフォルトの場所は <OS-tmpdir>/orygn-opa-mcp.log です。通常、Linux/macOS では /tmp/orygn-opa-mcp.log、Windows では %TEMP%\orygn-opa-mcp.log です。OPA_MCP_LOG_FILE で場所を変更できます。また、OPA_MCP_LOG_LEVEL=debug に設定すると、より多くのログが出力されます。

開発

git clone https://github.com/OrygnsCode/opa-mcp-server.git
cd opa-mcp-server
npm install
npm run dev

よく使うコマンド：

npm run lint              # ESLint
npm run typecheck         # tsc --noEmit
npm test                  # unit tests (Vitest)
npm run test:coverage     # unit + coverage report
npm run test:integration  # against real opa + regal binaries
npm run build             # compile to dist/

CI では、Ubuntu と Windows の Node 22、24、26、および macOS の Node 22 を対象に、プッシュと PR のたびに lint、typecheck、build、unit tests を実行します。Integration tests は Linux で実行し、Windows では必須ではないチェックとして、固定されたバージョンの opa、regal、conftest を使用して実行します。

ツールの追加、命名規則、ロギングの規律、リリースプロセスを含む、コントリビューター向けワークフロー全体については、CONTRIBUTING.md を参照してください。

バージョン管理とサポート

このプロジェクトはセマンティックバージョニングに従っています。SemVer における公開インターフェースは、登録済みのツール、プロンプト、リソース、それらの入出力スキーマ、認識される環境変数、および CLI エントリーポイントです。

破壊的変更は、以下のように行われます。

• 新しいメジャーバージョンのCHANGELOG.mdで告知されます。
• 少なくとも 1 回のマイナーリリースで、非推奨化の警告を事前に行います。
• リリース告知に移行に関する注意事項を添えます。

上流ツールチェーン（opa と regal）の固定バージョンは、運用者が管理する依存関係ではなく、ビルドの一部として扱います。Dockerfile と CI では同じバージョンを固定しており、更新は Dependabot または手動の PR を通じて行います。

ライセンス

MIT © Orygn LLC

@orygn/opa-mcp は独立したプロジェクトです。Open Policy Agent プロジェクト、Cloud Native Computing Foundation、Styra、Anthropic とは提携関係になく、承認や後援も受けていません。「Open Policy Agent」と「Rego」は、それぞれの所有者の商標です。「Model Context Protocol」は Anthropic, PBC の商標です。

OPA Ecosystemに掲載されています。