vibe-gate-mcp

Vibe-Gate (MCP)

面向 AI 辅助 IDE 的对抗式质量门：IDE Agent 与 Critic LLM 讨论代码；只有陷入僵局时才由人类决定。

快速开始（npm / npx）

1. 选择 Critic 提供商

使用带有对应密钥的直接 API 提供商，或使用已安装并登录的本地 CLI。本地 CLI 提供商无需单独的提供商 API 密钥。如果省略 CRITIC_PROVIDER，Vibe-Gate 会按以下顺序选择首个已安装的本地 CLI：Codex、Claude Code、Cursor Agent，然后是 OpenCode CLI。当 CRITIC_MODEL 使用 provider/model 格式时，OpenCode CLI 会移至首位。首次审查响应中会显示一条通知，说明所选 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 会传递给所选提供商或 CLI，不受 Vibe-Gate 的模型允许列表限制；提供商必须支持该模型 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. 调用工具（Agent）

{
  "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 会从磁盘读取完整文件，并在内部将 FILE/CONTENT 序列化后提供给 Critic。Agent 只需提供路径和完成情况报告，无需粘贴文件内容或生成语料库。示例使用 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 根据约定式提交选择版本（fix: 表示补丁版本，feat: 表示次要版本），将 vibe-gate-mcp 连同来源证明发布到 npm，并在 MCP Registry 中将该版本登记为 io.github.mustafacagri/vibe-gate-mcp。不会 存储令牌：npm 和 Registry 都通过 GitHub OIDC 信任此工作流。server.json 是 Registry 条目，并通过 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	环境变量 SSoT
examples/	Cursor mcp.json 模板

只读审查和完整源码槽位限制

对 submit_phase_review 设置 readOnly: true，即可执行不会改动工作区的检查。它会覆盖 updateStatus: true，并阻止清除/保存会话、更新状态、追加债务、更新冲突计数器以及写入死锁案例。判定结果和关注项验证仍遵循常规审查规则；死锁案例数据会返回，但不会保存。后续轮次可以读取已有的匹配会话，但只读调用不会保存新一轮内容。需要时，logToDebt 仍表示接受债务，但不会写入日志。默认值为 false。单独设置 updateStatus: false 只会禁用阶段状态更新。

每种载体（files[]、内联 semanticDiff、原始/JSON semanticDiffPath）都最多允许 十个实际的 FILE/CONTENT 源代码块，包括后续轮次中的额外 REQUEST: 上下文。重复代码块和重命名文件的两个端点分别计数，即使路径或字节内容相同也是如此。超出限制的语料会在扩大 Critic 请求前失败；不会缩减为前十个代码块。读取请求行范围时会读取完整文件，但仍受现有文件大小和总大小限制。Markdown、JSON 及其他文档/数据端点不接受作为源码上下文。调用方负责明确分类所选的源端点；files[] 允许 MCP 提供完整源码内容。对于已删除文件和重命名的旧端点，Vibe-Pilot 等编排器会先在实际快照路径中生成固定 Git 基础版本文件，再将这些路径传给 files[]。MCP 会从磁盘读取这些文件，不会自行读取 Git 历史记录。