vibe-gate-mcp

Vibe-Gate (MCP)

AI 支援 IDE 向けの敵対的品質ゲートです。IDE エージェントと Critic LLM がコードについて議論し、膠着状態になった場合にのみ人間が判断します。

クイックスタート（npm / npx）

1. Critic プロバイダーを選択する

API キーを使う直接 API プロバイダーか、インストール済みでサインイン済みのローカル CLI を使用します。ローカル CLI プロバイダーでは、別途プロバイダー API キーを用意する必要はありません。CRITIC_PROVIDER が省略された場合、Vibe-Gate はインストール済みのローカル CLI を次の順序で選択します。Codex、Claude Code、Cursor Agent、OpenCode CLI の順です。CRITIC_MODEL が provider/model 形式の場合、OpenCode CLI が最初に選択されます。最初のレビュー応答には、選択された CLI の名前を示す通知が含まれます。いずれも見つからない場合、OpenAI がデフォルトのままとなり、OPENAI_API_KEY が必要です。明示的に選択するには、CRITIC_PROVIDER を設定します。

パッケージの .env.example からコピーします。

# Direct API example
CRITIC_PROVIDER=openai
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

# Or use the signed-in Codex CLI account (no API key)
# CRITIC_PROVIDER=codex-cli

# Or another signed-in local CLI (no separate API key)
# CRITIC_PROVIDER=claude-code
# CRITIC_PROVIDER=cursor-agent
# CRITIC_PROVIDER=opencode-cli
# CRITIC_MODEL=provider/model  # required for opencode-cli; see `opencode models`

# Or OpenCode (https://opencode.ai/auth)
# CRITIC_PROVIDER=opencode
# OPENCODE_API_KEY=...
# OPENCODE_PLAN=go
# CRITIC_MODEL=minimax-m3

プロバイダー	CRITIC_PROVIDER	認証
OpenAI	openai	OPENAI_API_KEY
Anthropic	anthropic	ANTHROPIC_API_KEY
Google Gemini	google	GOOGLE_GENERATIVE_AI_API_KEY
MiniMax	minimax	MINIMAX_API_KEY
OpenCode	opencode	OPENCODE_API_KEY（任意で OPENCODE_PLAN）
Codex CLI	codex-cli	既存の codex login セッション
Claude Code	claude-code	既存の Claude Code アカウントセッション
Cursor Agent	cursor-agent	既存の agent login セッション
OpenCode CLI	opencode-cli	保存済みの opencode auth login 認証情報とモデル

Cursor Agent の場合、Vibe-Gate はまず agent を実行し、メインのコマンドが利用できない場合は、従来の cursor-agent 実行ファイルにフォールバックします。

opencode は引き続き別個の Zen/Go HTTP プロバイダーであり、OPENCODE_API_KEY が必要です。opencode-cli はローカル CLI を実行し、CRITIC_MODEL に provider/model 形式の値が必要です。詳細については CLI ガイドを参照してください。

CRITIC_MODEL は Vibe-Gate のモデル許可リストを介さず、選択したプロバイダーまたは CLI に渡されます。プロバイダーがそのモデル ID をサポートしている必要があります。OpenAI API プロバイダーは Responses API を使用します。プロバイダーの設定を参照してください。

CLI のインストール、ログイン、設定、OpenCode セッションの詳細、および評価したその他の候補については、CLI プロバイダーの設定と代替手段を参照してください。すべての変数の一覧は、docs/project/VARIABLES.mdを参照してください。

2. Cursor MCP を設定する（任意の利用リポジトリ）

Codex CLI 用のプロジェクトまたはユーザーの .cursor/mcp.json を使用します（またはAPI キーの例を使用します）。

{
  "mcpServers": {
    "vibe-gate": {
      "command": "npx",
      "args": ["-y", "vibe-gate-mcp"],
      "env": {
        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
        "CRITIC_PROVIDER": "codex-cli"
      }
    }
  }
}

直接プロバイダーを使う場合は、パッケージの隣にあるローカル .env、または VIBE_WORKSPACE_ROOT 配下の利用プロジェクト内にキーを保存してください（シークレットは決してコミットしないでください）。MCP の env は .env の設定を上書きします。CLI プロバイダーを使う場合は、MCP サーバーを実行する OS ユーザーと同じユーザーで CLI をインストールし、サインインしてください。

3. ツールを呼び出す（エージェント）

{
  "phaseId": "phase-1-§3",
  "report": "What changed, why, file:line — no TODOs",
  "files": ["src/a.ts", "src/b.ts"],
  "readOnly": true,
  "round": 1
}

変更したソースのパスを files[] に渡してください。 MCP はディスクからファイル全体を読み取り、Critic 用の FILE/CONTENT を内部でシリアライズします。エージェントが渡すのはパスと完了レポートであり、ファイル本文を貼り付けたり、コーパスを生成したりする必要はありません。この例では readOnly: true を指定して、レビュー状態が変更されないようにしています。docs/SEMANTIC_DIFF_PAYLOAD.mdを参照してください。

ローカル開発（このリポジトリ）

corepack yarn install
npm run build
npm test
cp .env.example .env   # fill Critic key
npm start              # stdio MCP

開発中にユーザー MCP を使用する場合：examples/cursor-mcp.user-local-dev.json（node dist/index.mjs と VIBE_WORKSPACE_ROOT=${workspaceFolder}）。

npm run build の実行後、IDE で vibe-gate MCP サーバーを再起動してください。

公開

リリースは自動で行われます。main へのプッシュごとに .github/workflows/publish.yml が実行され、yarn quality を実行し、semantic-release が Conventional Commits からバージョンを決定します（fix: はパッチ、feat: はマイナー）。その後、provenance 付きで vibe-gate-mcp を npm に公開し、MCP Registry に io.github.mustafacagri/vibe-gate-mcp として登録します。トークンは保存されません。npm とレジストリはいずれも GitHub OIDC を通じてワークフローを信頼します。server.json はレジストリのエントリーであり、scripts/sync-server-json.mjs によってリリースバージョンに保たれます。

yarn quality          # what the workflow checks before it tags anything
npm pack --dry-run    # inspect the exact tarball contents

利用者は、上記のとおり npx -y vibe-gate-mcp を使用します。

ペイロードのソース — files[] を優先

優先度	フィールド	用途
1	files[]	通常のバッチ
2	semanticDiffPath	既存の互換性用データ保持フィールド
3	semanticDiff	既存の互換性用データ保持フィールド

プローブには readOnly: true を使用してください。updateStatus: false と mcp-smoke- ／ vibe-gate-probe- のフェーズ接頭辞でスキップできるのは、フェーズステータスの書き込みのみです。

ドキュメント

ドキュメント	説明
docs/INSTALLATION.md	インストールとマルチリポジトリ MCP
docs/USAGE.md	初回実行とプロバイダー
docs/CLI_PROVIDERS.md	ローカル CLI プロバイダー
docs/SEMANTIC_DIFF_PAYLOAD.md	files[] の仕様
docs/ROADMAP.md	リリースチェックリスト
docs/TROUBLESHOOTING.md	古い MCP、パスエラー
docs/project/VARIABLES.md	環境変数の信頼できる情報源
examples/	Cursor の mcp.json テンプレート

読み取り専用レビューとソーススロットの上限

ワークスペースに変更を加えずにチェックするには、submit_phase_review で readOnly: true を設定します。これは updateStatus: true を上書きし、セッションの消去／保存、ステータスの更新、負債の追記、競合カウンターの更新、デッドロックケースの書き込みを防ぎます。判定と懸念事項の検証には通常のレビュー規則が引き続き適用されます。デッドロックケースのデータは返されますが、保存されません。既存の一致するセッションは後続のラウンドで読み取れますが、読み取り専用の呼び出しでは新しいラウンドは保存されません。負債の受け入れが必要な場合、logToDebt は引き続きその意思を示しますが、ログは書き込まれません。デフォルトは false です。updateStatus: false のみを指定した場合は、フェーズステータスの更新だけが無効になります。

すべてのデータ保持フィールド（files[]、インラインの semanticDiff、raw／JSON の semanticDiffPath）には、後続ラウンドで追加される REQUEST: コンテキストを含め、実際の FILE／CONTENT ソースブロックが 10 個までという上限があります。パスやバイト列が同じでも、重複するブロックとリネームの両端はそれぞれ個別に数えられます。上限を超えるコーパスは、拡張された Critic リクエストを行う前に失敗し、先頭の 10 ブロックだけに切り詰められることはありません。指定された行範囲は、既存のファイルサイズと合計サイズの上限に従い、ファイル全体として読み取られます。Markdown、JSON、その他のドキュメント／データのエンドポイントは、ソースコンテキストとして拒否されます。呼び出し元は、選択したソースエンドポイントを明示的に分類します。files[] を使うと、MCP がソース本文全体を提供できます。削除されたファイルやリネーム前のエンドポイントについては、Vibe-Pilot などのオーケストレーターが、ピン留めされた Git のベースブロブを実際のスナップショットパスに実体化してから、そのパスを files[] に渡します。MCP はディスク上のファイルを読み取りますが、Git 履歴自体は読み取りません。