codex-mcp

QA成果物のための、独立した読み取り専用の品質ゲート。

codex-mcp は、スタンドアロンのMCPサーバーで、Codexを敵対的なセカンドレビューアとして、候補となるテストケースやバグ指摘に対して実行します。これは、作成エージェントが最終レポートを書く前に行われます。Codexはリポジトリ自体を調査し、何をカバーすべきか、または欠陥が本物かどうかについて独自の見解を形成し、その後に初めて、与えられた候補とそれを比較します。

レビューデルタを返します。あなたの成果物を書き換えることは決してありません。

Authoring agent (Claude, or any MCP client)
        │  gathers the requirement, reads the code, drafts candidates
        ▼
  candidate result — in memory, not yet written
        │
        ▼  codex_qualify
   codex-mcp ──► Codex (read-only sandbox, rooted at your repo)
        │           ├─ reads the code, the diff, the existing tests
        │           ├─ reads blast-radius / test-charter if present
        │           └─ reads Jira / DB / other MCPs if configured, read-only
        ▼
  review delta: accept · modify · remove · missing · evidence · limitations
        │
        ▼
Authoring agent reconciles, then writes the FINAL artifact

目次 · インストール · プロジェクトへの接続 · 使用方法 · 設定 · エビデンスコネクタ · 権限境界 · API契約 · トラブルシューティング · テスト

なぜセカンドモデルなのか、そしてなぜ読み取り専用なのか

このツールが対処する失敗モードは、「エージェントがテストケースを書けない」ということではありません。それは、自分の作業を採点するエージェントが自分自身と同意してしまうことです。作成者のコンテキストを共有するレビューアは、作成者の盲点を継承します。

したがって、2つの特性が重要です。

独立性。 Codexは、候補を詳しく見る前に期待されるカバレッジを導き出すようにプロンプトされ、バグの主張を確認するのではなく反証しようとします。最初に候補にアンカーを置くと、より同調的なレビューアになり、有用性が低くなります。

読み取り専用。 レビューアはCodexのread-onlyサンドボックスで実行され、到達可能なすべてのダウンストリームシステムは、各ツールを分類し、変更するものを拒否するポリシーレイヤーを通過します。ライブリポジトリに安全にポイントできない品質ゲートは、誰も実行しない品質ゲートです。

どちらのモデルも権威的ではありません。ソースのエビデンスは次のとおりです。

requirement / runtime / code / DB / external evidence  >  model opinion

Related MCP server: gpt-control

インストール

Node 20+ が必要です。マシンごとに1回、4つのコマンド。

# 1. The Codex CLI. codex-mcp drives it, and it owns your credentials.
npm install -g @openai/codex@latest

# 2. codex-mcp itself.
git clone <this-repo> codex-mcp && cd codex-mcp
npm install && npm run build && npm link

# 3. Sign in. A browser opens once; that is the whole flow.
codex-mcp login

# 4. Write a config, detecting any MCP servers already on this machine.
codex-mcp init --model gpt-5.6-sol

次に、信頼する前に確認します。

codex-mcp doctor

すべての行がokと読めるはずです。doctorは読み取り専用で、ライブプロジェクトに対して安全です。各失敗の意味についてはトラブルシューティングを参照してください。

npm名codex-mcpは無関係なパッケージに属しています。上記のようにソースからインストールするか、独自のスコープで公開してください。

initの機能

~/.config/codex-mcp/codex-mcp.yamlと、従来の場所にダウンストリームMCPサーバーが見つかった場合は、その隣に.envを書き込みます。

$ codex-mcp init --dry-run
Would write into /home/you/.config/codex-mcp
  codex-mcp.yaml  (new)
  .env            (new)

Detected:
  jira-mcp (jira) -> /home/you/jira-mcp/src/index.js
  db-mcp (database) -> /home/you/db-mcp/dist/index.js

検出されたサーバーは、有効化できるコネクタエントリとして書き込まれ、そのパスは.envに保持されるため、YAMLはマシン間で移植可能です。--forceは上書きします。それがない場合、既存のファイルは保持されます。

initは、唯一何かを書き込むコマンドであり、レビューが存在する前に実行されます。レビュー自体は厳密に読み取り専用です。

設定を自分で書きたいですか？ codex-mcp.example.yamlを~/.config/codex-mcp/codex-mcp.yamlにコピーしてください。すべての値に注釈が付けられており、コメントに別段の記載がない限り、組み込みのデフォルトです。

認証

マシンごとに1回のコマンド:

codex-mcp login          # browser opens; sign in to ChatGPT
codex-mcp auth-status    # confirm

資格情報は、Codex CLIの独自のストア（~/.codex/auth.json、モード0600）に保存され、CLIによって更新されます。再起動やターミナルをまたいで保持されます。プロジェクトやセッションごとに再ログインする必要はありません。

codex-mcpは資格情報自体を処理しません。 OAuthクライアント、コールバックリスナー、トークンストレージはありません。codex login statusをシェルアウトして、yes/noを読み取ります。ここでは、レビュー中にブラウザを開くことはできません。認証されていない呼び出しは、代わりに迅速に失敗します。

{ "code": "CODEX_AUTH_REQUIRED", "message": "Codex is not authenticated. Run `codex-mcp login`." }

APIキーの使用

codex-mcp login --mode api                    # hidden prompt
printenv OPENAI_API_KEY | codex-mcp login --mode api

キーは--api-key、次にOPENAI_API_KEY、次に非表示のプロンプトから読み取られ、stdinを介してcodex login --with-api-keyにパイプされます。argv要素としては決して使用されないため、プロセステーブルとシェル履歴に残りません。Codex CLIが保存します。codex-mcpは保存しません。

設定でauth.modeを一致させます。CLIが設定で主張するモードと異なるモードで認証されている場合、レビューは誤って間違ったアカウントに請求するのではなく、明確なエラーで失敗します。

プロジェクトへの接続

1つを選択してください。2回登録するのは最も一般的なセットアップミスです。以下の警告を参照してください。

オプションA — 1つのプロジェクト、コミット済み

プロジェクトルートに.mcp.jsonを作成します。.claude/ではなく、別のファイルセットを保持し、それを無視します。

{
  "mcpServers": {
    "codex-mcp": { "command": "codex-mcp", "args": ["start"] }
  }
}

コミットします。インストールを実行したすべてのチームメイトは、独自の設定から独自のモデル選択を使用して、ゲートを利用できるようになります。

オプションB — すべてのプロジェクト、コミットされていない

claude mcp add codex-mcp -- codex-mcp start

これは~/.claude.jsonに書き込み、どこでも適用されます。

1つの場所にのみ登録してください。 claude mcp addはローカルスコープで書き込み、これは.mcp.jsonよりも優先されます。両方存在する場合、プロジェクトファイル（その中のenvを含む）は静かに無視されます。.mcp.jsonに切り替える場合は、claude mcp remove codex-mcpを実行してください。

Claude Codeを再起動します。/mcpにcodex-mcpが3つのツールでリストされるはずです。そうでない場合は、トラブルシューティングを参照してください。

他のMCPクライアントも同じ2つのフィールド（command: codex-mcp、args: ["start"]）を、使用する設定ファイルに取ります。

使用方法

自動化する

プロジェクトのCLAUDE.mdに1つのルールを追加します。これが統合サーフェス全体です。プロジェクト固有のCodexロジックはどこにもありません。

## Independent QA qualification

Before finalizing test cases or bug reports, send the complete candidate result,
project root, task/requirement context, and any available blast-radius or
test-charter to codex-mcp for independent qualification.

Reconciling means verifying each objection against the evidence it cites — not
accepting it. Apply what the evidence supports. Reject what it does not, and note
why. codex-mcp is a second opinion, not an approver.

One pass is normal. Run a second only if the first forced substantial high-risk
changes.

これで、通常のリクエストを書くと、ゲートが自動的に実行されます。

DEV-2951のテストケースを作成してください。

エージェントは要件を収集し、コードを読み、候補をドラフトし、codex_qualifyを呼び出し、調整してからレポートを書きます。

明示的に要求する

ルールがない場合、または既にドラフトされたものに適用したい場合:

レポートを書く前に、これらのテストケースをproject.rootを/path/to/repoに設定し、task.idをDEV-2951にしてcodex-mcpに送信してください。それが何に反対し、あなたが同意するかどうかを示し、最終バージョンを書いてください。

今書いたバグ調査結果をreviewType: "bugs"でcodex_qualifyに通してください。それが誤検知と呼ぶものについては、調査結果を削除する前に、それが引用するコードを確認してください。

これらをcodex-mcpに対して評価してください。ただし、引用されたエビデンスが実際に成立する場合にのみ、反対意見を報告してください。どれを拒否したか、その理由を教えてください。

便利なバリエーション:

返ってきたものを読む

エージェントに、静かに処理するのではなく、これらを表面化するように依頼してください。

• missing — カバーが不足していると主張するもの。引用されたfile:lineが実際に存在するか確認してください。

• modify — あなたの期待がコードと矛盾している。通常、最も鋭い指摘です。

• remove — 冗長。それがあなたのものを置き換えると主張するものが実際にそうであるか確認してください。

• limitations — 検証できなかったもの。長い制限リストを持つ自信に満ちたレビューは、狭いレビューです。残りを信頼する前にこれを読んでください。

• disagreements — あなたのエージェントとそれが同じエビデンスを異なる方法で読んだ。これらは、どちらかのモデルではなく、あなたが必要です。

良いフォローアッププロンプト:

各反対意見について、それが引用したエビデンスと、あなた自身がそれを検証したかどうかを教えてください。拒否したものを理由とともにリストしてください。

それがしないこと

ファイルを編集したり、コミットしたり、プッシュしたり、Jiraやデータベースに書き込んだり、レポートを書いたりすることはありません。エージェントがcodex-mcpが何かを変更したと主張する場合、それはしていません。git statusを確認してください。

調整 — 重要な部分

codex-mcpは、Codexを受け入れるように指示することはありません。すべての応答には次のものが含まれます。

{
  "reconciliation": {
    "instruction": "This is an independent second opinion, not a verdict...",
    "codexIsNotAuthoritative": true
  }
}

Codex objection
      │
      ▼
Author verifies the cited evidence
      │
      ├─ evidence supports it   → apply
      ├─ evidence does not      → reject, and record why
      └─ unclear                → investigate

次に、あなたが最終成果物を書きます。

ループ保護

review.maxPasses（デフォルト2）はサイクルを制限します。パス1は通常のケースです。パス2は、大幅な高リスクの変更を強制したレビューのために存在します。制限を超えるリクエストは拒否され、meta.furtherPassesAllowedは予算が使い果たされたときに通知します。2つのモデルが同意するまで反復することが目標ではありません。同意は安価であり、それに到達することは通常、一方が思考を停止したことを意味します。

設定

設定は**~/.config/codex-mcp/codex-mcp.yaml**にあります。編集するファイルはこれだけです。codex-mcp.example.yamlは注釈付きバージョンで、現在のCodexモデルIDが含まれています。

設定ファイルが存在しない場合も完全にサポートされています。サーバーはデフォルト（安全なもの）で起動します。失うのはモデルの固定とすべてのコネクタです。コネクタはYAMLでのみ定義できるためです。

モデルの場所

review:
  model: gpt-5.6-sol
  requireModel: true

3つのレイヤーが設定できます。最も高いものが優先されます。

モデルは1つのレイヤーに保持してください。2つの場所に設定されたキーは、下のコピーを無効にします。編集しても何も起こらないように見えます。doctorは、モデルが両方に設定され、2つが異なる場合に警告します。

チーム全体でプロジェクトを固定するには、オプションAの.mcp.jsonにenvを追加します。

{
  "mcpServers": {
    "codex-mcp": {
      "command": "codex-mcp",
      "args": ["start"],
      "env": { "CODEX_MODEL": "gpt-5.6-sol", "CODEX_REASONING_EFFORT": "high" }
    }
  }
}

これにより、全員が同じレビューアを確実に受け取れます。これは、チーム全体で調査結果を比較する場合に非常に価値があります。コスト: そのモデルに対してCodex CLIが古すぎるチームメイトは、codex updateを実行するように指示するCODEX_MODEL_NOT_AVAILABLEエラーを受け取ります。この失敗は意図的です。代替案は、彼らが静かに弱いレビューアを受け取り、その判断を信頼することです。

どのモデル。 フロンティアモデルを優先してください。ここでの価値は、作成エージェントが見逃したものをキャッチすることであり、安価なレビューアは、表示されたものにほとんど同意します。共有ゲートにrequireModel: trueを設定して、Codexのデフォルトの変更が静かにレビュー品質を変えないようにします。利用できないモデルはCODEX_MODEL_NOT_AVAILABLEを発生させます。codex-mcpは別のモデルにフォールバックしません。

すべての設定とその環境変数

優先順位: 環境 > codex-mcp.yaml > デフォルト。 変数は、ファイルを編集せずに1つのYAML値をオーバーライドするために存在します。.mcp.jsonのenvでプロジェクトを固定するか、シェルで1回限りのために使用します。

コネクタ設定はその優先順位を逆転させます。YAML が優先されます。それは、YAML がコネクタごとの明示的な意図であり、これらの変数は YAML に別段の指定がない場合の大まかなフォールバックにすぎないからです。

これらのトグルはコネクタの**名前（種類ではありません）**に一致します。jira-mcp や db-mcp という名前のコネクタは jira にも database にも一致しないため、どちらも CUSTOM_MCPS_ENABLED に該当します。YAML に enabled: を設定すれば、この問題は完全に回避できます。

2 つの変数には YAML に相当するものがありません。これらは設定ファイルが見つかる前に読み取られるためです。CODEX_MCP_CONFIG（設定ファイルへのパス）と XDG_CONFIG_HOME（~/.config/codex-mcp/ が検索される場所）です。

設定ファイルの検索場所

最初に見つかった場所が優先されます:

--config <path>  →  $CODEX_MCP_CONFIG  →  ./codex-mcp.yaml  →  ~/.config/codex-mcp/codex-mcp.yaml

doctor は、どれを読み込んだかを出力します。選択されたファイルの隣に .env があれば読み込まれますが、必須ではありません。.env を持つ価値があるのは、マシンごとに異なる値、つまり YAML が ${JIRA_MCP_PATH} として参照するコネクタパスだけです。そして、そうした値にも、代わりに ${VAR:-fallback} というデフォルトを設定できます。

.env や YAML に資格情報を絶対に置かないでください。 CHATGPT_TOKEN、SESSION_TOKEN、ACCESS_TOKEN、REFRESH_TOKEN は完全に無視され、それらが存在すると設定の警告として報告されます。Codex の認証は Codex CLI と OS の資格情報ストアに属するものです。

エビデンスコネクタ

Codex が Jira やデータベースと直接通信することはありません。接続先は codex-mcp エビデンスブローカーです。これは独立した読み取り専用プロセスで、各ダウンストリームサーバーのツールを発見して分類し、ポリシーを通過したものだけを転送します。しかも、発見時だけでなく、すべての呼び出しで再チェックします。

# ~/.config/codex-mcp/codex-mcp.yaml
connectors:
  jira-mcp:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/jira-mcp/src/index.js']
    cwd: /path/to/jira-mcp

  db-mcp:
    enabled: true
    kind: database
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/db-mcp/dist/index.js']
    cwd: /path/to/db-mcp
    allowTools: ['execute_query']
    denyTools: ['update_query']
    maxRows: 500
    timeoutMs: 10000

kind は正規化を安定した語彙に導きます — requirement.read、database.query_readonly、testmanagement.search、external_file.read です。これにより、レビュアーのプロンプトは、コネクタがそれを getJiraIssue と呼ぶか get_jira_ticket と呼ぶかを知らなくても、「要件」を要求できます。マッピングされていないツールも、独自の名前のまま公開されます。新しい読み取り向け MCP を追加するのにコードの変更は必要ありません。

ダウンストリームサーバーが受け取るのは、PATH、HOME、および自身の設定が宣言する env だけです。codex-mcp プロセスの環境変数は絶対に受け取りません。

到達できないコネクタは、レビューを失敗させるのではなく、レビューを記録された制限事項に格下げします。エビデンスの欠落はレビューに関する事実であり、レスポンスにもその旨が記載されます。

コネクタを追加したら codex-mcp doctor を実行してください。各コネクタの行には、公開されたツールの数と、ポリシーによって保留されたツールの数が表示されます:

[  ok  ] Connector: jira-mcp
           4 read-only tool(s) exposed, 0 withheld by policy.
[  ok  ] Connector: db-mcp
           6 read-only tool(s) exposed, 1 withheld by policy.

許可を求める — approval フィールド

手渡されたプロジェクトを読むのに許可は必要ありません。project.root を指定したのですから、それを読むこと自体がリクエストです。その外側に到達すること — チケットトラッカー、本番データベース、ファイルサーバーなど — は別の判断です。数週間前に書かれた設定ファイルの enabled: true は、今日のレビューに対するインフォームドコンセントにはなりません。

プロンプトは MCP のエリシテーションを介して配信されるため、MCP クライアント内の人間に届きます。クライアントがプロンプトを表示できない場合、そのコネクタはスキップされ、limitations に記録されます。黙って許可されることはありません。誰にも見えないプロンプトは同意ではありません。すでに審査済みのコネクタには approval: trusted を設定してください。

要件

jira 種類のコネクタが設定され、task.id が設定されている場合、Codex はチケット自体を読み取り、渡された要件テキストを作成エージェントの解釈として扱います。つまり、照合すべき主張であり、情報源ではありません。コネクタがない場合は、提供されたテキストにフォールバックし、それを独立に検証できなかったことを記録します。

データベース

参照されるのは、評決を変えうる場合だけです。永続性、リレーションシップ、テナントの所有権、状態遷移、マイグレーション、データ整合性、報告された欠陥の検証などです。プロンプトにはその旨が明示されており、ポリシーレイヤーが残りを強制します。

読み取り専用のデータベースアカウントを使用してください。codex-mcp はすべての変更ステートメントを拒否します。しかし、読み取り専用の権限付与は、このサーバーが正しく動作することに依存しない境界です。

権限の境界

中心となるルール: Codex は広く調査でき、変更は一切行いません。

「広く」を文字どおりに読んでください。あなたが気にかけている秘密を保持するマシンにこれを向ける前に、下の読み取り範囲を参照してください。

強制は、以下のレイヤーで行われます:

1. Codex 自身の read-only サンドボックス — 主要な境界です。

2. コマンドポリシー — argv ベースで、デフォルトは拒否です。不明なバイナリは拒否されます。シェルラッパーは、そのペイロードを分類できないため拒否されます。

3. SQL ポリシー — コメントと文字列リテラルはキーワードスキャンの前に除去されるため、変更操作を引用符で囲まれた値の内側に隠すことはできません。呼び出しごとに 1 つのステートメントのみ許可され、クエリに制限がない場合は行数上限が注入されます。

4. ツールポリシー — すべてのダウンストリーム MCP ツールは read / write / destructive / unknown に分類され、read だけが公開されます。unknown は、明示的に許可リストに登録されない限り拒否され、許可リストがあっても変更を伴うツールを救うことはできません。議論して通り抜けられる境界は、境界ではありません。

分類器は意図的に非対称です。変更の兆候が少しでもあれば、読み取りの兆候に優先します。公開されるには、ツールがはっきりと読み取り専用に見える必要があります。安全でないように聞こえるが実際は安全なツールは、設定 1 行のコストで済みます。安全に聞こえるが実際は安全でないツールは、データを失うコストがかかります。

tests/security/ は、拒否された呼び出しがダウンストリームサーバーに決して到達しないことや、レビュー後にフィクスチャリポジトリがバイト単位で同一であることなど、これらすべてを検証します。

読み取り範囲はプロジェクトより広い

Codex の read-only サンドボックスが制約するのは書き込みであり、読み取りではありません。その中で Codex は、あなたのユーザーアカウントが読み取れるすべてのファイルを読むことができます。project.root 配下のファイルだけではありません。直接検証済み:

$ codex exec --sandbox read-only -C ./proj   "read ../outside.txt"
exec  sed -n '1,$p' ../outside.txt   in .../proj
      succeeded: SECRET_OUTSIDE=canary-9f3a2b

Codex CLI には読み取り範囲を狭めるオプションはありません。sandbox_permissions はさらなるアクセスを許可するだけです。したがって、保証を正直に述べると次のとおりです:

どこであっても、何も変更されません。読み取りは、project.root ではなく、 OS のファイル権限によって制限されます。

project.root はレビュアーがどこを見るかを左右します。それは作業ディレクトリであり、プロンプトの主題ですが、読み取りの牢獄ではありません。

実際には次のことを意味します:

• あなたのユーザーが読み取れる場所にある .env、秘密鍵、資格情報ファイルはレビュアーから到達可能であり、その内容はモデルのコンテキストの一部として OpenAI に送信される可能性があります。

• codex-mcp 自身の成果物パス封じ込め（assertArtifactPathAllowed）は、codex-mcp がプロジェクト外のファイルをプロンプトへ読み込むことを防ぎます。これは、Codex が自身のサンドボックス内で読み取る内容を制約するものではなく、制約することもできません。

• 調査結果はログに記録される前に編集されますが、それはログ管理のための制御であり、封じ込めのための制御ではありません。

それがあなたの環境にとって重要なら、プロジェクトだけをマウントしたコンテナまたは VM 内で codex-mcp を実行してください。今日、読み取りを制限する唯一の信頼できる方法はこれです。

レビュアーが設計上読み取るもの

プロジェクトルート内では、ドットディレクトリを含むすべてを読み取ります。.claude、.cursor、.github、またはチーム独自の .qa をレビュアーから隠すと、プロジェクトがレビュアー向けに書き留めたルールそのものを無視する結果になります。既知のツールキャッシュ（.venv、.pytest_cache、.next など）は一覧には残りますが、読み取り対象として推奨されることはありません。

規約ファイル — CLAUDE.md、AGENTS.md、CONTRIBUTING.md、TESTING.md、.cursorrules、CODEOWNERS — は、「最初にこれらを読んでください」としてプロンプトに提示されます。

契約

codex_qualify

必須: reviewType、project.root、およびレビュータイプに一致する候補セット。それ以外はすべて任意で、レビューをブロックすることはありません。

{
  "reviewType": "test-design",

  "project": { "root": "/absolute/path/to/project", "branch": "feature/DEV-123" },

  "task": {
    "id": "DEV-123",
    "source": "jira",
    "title": "Archive a resource",
    "description": "A user may archive a resource belonging to their own tenant.",
    "acceptanceCriteria": ["Archiving an active resource sets status to archived."]
  },

  "artifacts": {
    "blastRadiusPath": "docs/blast-radius.md",
    "testCharterPath": "docs/test-charter.md"
  },

  "candidate": {
    "testCases": [{ "id": "TC-001", "title": "Archive an active resource", "priority": "high" }],
    "bugs": []
  },

  "options": { "useJira": true, "useDatabase": true, "useExternalMcps": true }
}

候補はペイロード内で運ばれます。まだどこにも書き込まれておらず、一時的なレポートファイルを必須にすることは、その目的を無意味にします。

成果物パスは project.root 内で解決されます。そこから外れるパスは拒否されます。

レビュータイプ

テスト設計の結果

{
  "status": "CHANGES_REQUIRED",
  "summary": { "accepted": 18, "modify": 2, "remove": 1, "missing": 3 },
  "accepted": ["TC-001", "TC-002"],
  "modify": [{
    "candidateId": "TC-014",
    "reason": "Expected state contradicts persistence logic.",
    "evidence": [{ "source": "code", "location": "src/session/service.ts:143" }],
    "recommendation": "Queue should remain persisted after this transition."
  }],
  "remove": [{ "candidateId": "TC-022", "reason": "Duplicates TC-018.", "supersededBy": "TC-018" }],
  "missing": [{
    "title": "Verify cross-tenant access is rejected",
    "priority": "high",
    "dimension": "authorization",
    "reason": "Target lookup accepts an externally supplied identifier.",
    "evidence": [{ "source": "code", "location": "src/resource/controller.ts:82" }]
  }],
  "disagreements": [],
  "limitations": []
}

バグの結果

{
  "status": "CHANGES_REQUIRED",
  "summary": { "verified": 1, "falsePositive": 1, "needsMoreEvidence": 0, "other": 0 },
  "findings": [{
    "candidateId": "BUG-003",
    "verdict": "FALSE_POSITIVE",
    "confidence": "high",
    "severityAssessment": null,
    "reason": "Ownership validation occurs in router-level middleware.",
    "evidence": [
      { "source": "code", "location": "src/routes/users.ts:42" },
      { "source": "code", "location": "src/middleware/access.ts:91" }
    ],
    "recommendation": "Remove the finding unless runtime evidence contradicts the middleware."
  }],
  "limitations": []
}

status: PASS · CHANGES_REQUIRED · INCONCLUSIVE · ERROR

verdict: VERIFIED · FALSE_POSITIVE · NEEDS_MORE_EVIDENCE · SEVERITY_DISAGREEMENT · DUPLICATE_OR_ALREADY_COVERED · INCONCLUSIVE

エンベロープが保証すること

codex-mcp はレビュアーの出力を返す前に正規化します。なぜなら、リストを採点するモデルは時々逸脱するからです：

• レビュアーが発明したIDは、メモ付きで削除されます — 存在しないテストケースへの参照に対して行動することはできません；

• レビュアーが言及しなかった候補は 未レビュー として記録され、承認に昇格することはありません。沈黙は承認ではないからです；

• 判定のないバグは明示的な INCONCLUSIVE になります；

• summary のカウントは配列から再計算されます；

• status はレビュアーの自己評価ではなく、デルタから導出されます。

meta.evidence はレビューが実際に何に基づいていたかを報告します — git、blast-radius、test-charter、requirementアクセスが利用可能だったかどうか、どのコネクタが到達可能だったか。プロジェクトパス自体は決してログに記録されたり返されたりしません。meta.evidence.projectRootId はハッシュです。

codex_auth_status

Codexが認証されているかどうか、どのモードで、それが設定された auth.mode と一致するかどうか。資格情報を返すことはありません。

codex_capabilities

診断用。このインスタンスが到達できる証拠、どのダウンストリームツールが差し控えられたか、その理由、そしてレビュアーが実行を禁止されていることの明示的なリスト。

CLI

codex-mcp init         # write ~/.config/codex-mcp/, detecting local MCP servers
codex-mcp start        # run the MCP server on stdio (what a client launches)
codex-mcp login        # authenticate (--mode chatgpt|api)
codex-mcp auth-status  # report auth state, never credentials
codex-mcp doctor       # diagnose everything; mutates nothing

init は --model <id>、--force、--dry-run を受け取ります。start と doctor は --config <path> を受け取ります。doctor はさらに --project <path> と --json も受け取ります。

codex-mcp broker は内部用です — Codexが起動するエビデンスブローカーです。手動で実行することはありません。

トラブルシューティング

doctor が報告するすべては、ok、warn（動作するが、あるべき状態より緩い）、または FAIL（レビューが機能しない）のいずれかです。

エラー

安定したコードで、分岐しても安全です。ペイロードはプロセスを離れる前に編集されます。

CODEX_AUTH_REQUIRED              CODEX_NOT_INSTALLED
CODEX_MODEL_NOT_CONFIGURED       CODEX_MODEL_NOT_AVAILABLE
INVALID_PROJECT_ROOT             PROJECT_ACCESS_DENIED
INVALID_REVIEW_REQUEST           INVALID_REVIEW_TYPE
DOWNSTREAM_MCP_UNAVAILABLE       DOWNSTREAM_MCP_PERMISSION_DENIED
DB_QUERY_DENIED                  DB_QUERY_TIMEOUT
CODEX_EXECUTION_FAILED           CODEX_OUTPUT_INVALID
REVIEW_TIMEOUT                   INTERNAL_ERROR

Codexがスキーマに一致しない出力を返した場合、codex-mcp は再分析を禁止する明示的な修正を付けて 一度だけ 再試行します。それも失敗した場合は CODEX_OUTPUT_INVALID を返します。部分的に解析されたレビューを返すことはありません — それに基づいて行動することになるからです。

可観測性

構造化JSONを stderr に出力します（stdoutはMCPトランスポートに属します）。ログに記録されるもの：レビューIDとタイプ、ハッシュ化されたプロジェクトID、モデル、タイミング、コネクタの可用性、候補数、Codexの終了ステータス、スキーマ検証ステータス。

決してログに記録されないもの：トークン、パスワード、DB資格情報、クッキー、ソース内で見つかったシークレット。編集は debug を含むすべてのレベルで実行されます。

テスト

5つのレイヤー、最も安価なものから順に。それらを下っていきます — あるレイヤーでの失敗は、次のレイヤーの結果を無意味にします。

1. 自動スイート — 無料、オフライン、約7秒

npm install
npm run build
npm test
npm run typecheck

偽のCodex CLIと意図的に敵対的な偽のMCPサーバーに対する400以上のテスト。ネットワークなし、モデル呼び出しなし、決定的。これはすべての変更時とCIで実行するものです。

tests/security/ は読む価値のある部分です：ファイル編集、コミット、プッシュ、イシュー書き込み、DB変更が拒否されることを検証し、拒否された呼び出しがダウンストリームサーバーに到達しないことを検証します。

2. doctor — このインストールは正しく配線されているか

codex-mcp doctor
codex-mcp doctor --project /path/to/repo

読み取り専用で、ライブプロジェクトに対して安全です。Node、Codex CLI、認証、認証 モード の一致、モデル、サンドボックス、設定ファイル、および設定されたすべてのコネクタをチェックします。

3. codex_capabilities — 実際に到達できる証拠は何か

doctor はカウントを提供します。これはツールごとの内訳を提供し、各差し控えられたツールが なぜ 差し控えられたかも含みます。MCPクライアントから呼び出すか、または：

node -e "
import('./dist/src/config/config.js').then(async ({loadConfig}) => {
  const {CodexMcpServer} = await import('./dist/src/server.js');
  const {Logger} = await import('./dist/src/util/logger.js');
  const s = new CodexMcpServer({config: loadConfig(), logger: new Logger('error', {}, {write(){}})});
  console.log(JSON.stringify(await s.callToolForTesting('codex_capabilities', {}), null, 2));
  process.exit(0);
});"

期待するツールが allowedTools にあること、および deniedTools のすべてのエントリが 望む 拒否であることを確認してください。通常とは異なる名前の読み取り専用ツールは deniedTools に unknown として入ります — そのコネクタの allowTools に追加してください。

4. npm run try — 実際のレビュー、実際のモデル、実際のコスト

これは予算を費やす唯一のレイヤーです。認証、モデル、サンドボックス、証拠収集、コネクタ、プロンプト、構造化出力の全体のパスを証明します。

npm run try -- --project /path/to/repo
npm run try -- --project /path/to/repo --type bugs
npm run try -- --project /path/to/repo --type combined --task DEV-123
npm run try -- --project /path/to/repo --candidates ./candidates.json --json

--candidates なしで、既知の欠陥 を含むセットを送信します — 2つの重複、コードが矛盾する1つのアサーション、およびいくつかの明らかなギャップ。それがポイントです：レビュアーをテストしているので、正しい答えがすでにわかっている入力を使用します。

それを判断する基準：

• 重複を remove に入れましたか？

• 矛盾するアサーションをコードを引用して modify に入れましたか？

• すべての missing エントリに実際の file:line がありますか、曖昧な領域ではありませんか？

• その後リポジトリは変更されていませんか（git status）？

シードされたセットでの PASS は何かが間違っていることを意味します、コードがクリーンであることを意味しません。

--candidates を独自のJSONで指定して、実際のワークフローをリハーサルします：

{ "testCases": [{ "id": "TC-1", "title": "..." }], "bugs": [] }

5. エンドツーエンドのフィクスチャ — オプトイン

CODEX_MCP_E2E=1 npm test -- tests/e2e

実際のカバレッジギャップ（冪等性）と、ルーターミドルウェアがすでに反証するバグレポートを含むフィクスチャリポジトリを構築し、実際のCodex CLIに対して完全な資格認定を実行し、フィクスチャがその後バイト単位で同一であることを検証します。数分かかります。

MCPサーバーとして駆動する

上記のレイヤーが合格したら、クライアントが行う方法で駆動します：

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | codex-mcp start

次に、Claude Codeに登録し、実際のチケットで使用します。

開発

src/
  config/      resolution, precedence, validation
  auth/        Codex CLI delegation for both auth modes
  codex/       process spawning, argv construction, output parsing
  review/      orchestration, per-type reviewers, output normalization
  evidence/    repository, git, artifacts, requirement, database, external
  mcp-broker/  downstream clients, discovery, classification, the broker server
  policy/      command, SQL, MCP-tool, permission, and consent decisions
  prompts/     base reviewer, test-design, bug-review
  schemas/     public request and result contracts
  tools/       the three MCP tools

ライセンス

MIT