@project-value-lab/gate-mcp

实验状态（experimental · 0.x）：本包处于公开实验期。工具入参/出参契约在 0.x 内可能有向后不兼容调整（每次变更记入 changelog 并升 minor）；决策卡字段以服务端 OpenAPI（docs/openapi/gate.yaml）为准。生产流水线钉住精确版本使用；1.0.0 前不承诺长期稳定接口。

ProjectValueLab 依赖门禁的 MCP server（N3）。把 POST /v1/gate/assess 与 GET /v1/gate/decisions/:id 包装为两个 MCP 工具，供 Claude Code / Cursor 等 MCP 客户端在编码现场做"引入这个依赖前先过门禁"。

工具

工具	入参	出参
assess_dependency	ecosystem（npm/pypi/go/maven/cargo/nuget/rubygems）、package、version、usageContext?	完整决策卡对象：recommendation（GO/VALIDATE/DROP）、hardGates[]、evidence[]、explanation、scorecardRef、decisionUrl、cached、evaluatedAt、policyVersion、signalGaps[]
get_decision	decisionId（= assess 返回的 scorecardRef，64 位 hex）	同上（读回已存在决策，只能读本工作区的）

输出即 HTTP API 的决策对象本体（structuredContent + JSON 文本双形态），含可引用、可审计的 decisionUrl（读回需同工作区的 Bearer key，不是公开链接——不要为分享它而外发 key）。

安装与配置

# 仓库根目录：打包（prepack 自动先 build）+ 全局安装
npm pack ./packages/gate-mcp   # 注意 ./ 前缀——裸路径会被 npm 当成 GitHub shorthand
npm install -g ./project-value-lab-gate-mcp-<version>.tgz

环境变量（key 既不进命令行参数、也不明文写进任何可能提交/同步的配置文件）：

• PVL_GATE_URL：ProjectValueLab 后端 base URL（如 https://pvl.example.com）。
• PVL_GATE_API_KEY：工作区 API key（pvl_live_…）。在 PVL 账户页创建，明文只显示一次。可省略——省略时进入匿名 hosted 模式（见下）。

匿名（hosted）模式

不设 PVL_GATE_API_KEY 时，assess_dependency 走公开端点 POST /v1/public/gate/assess（服务端需开启 PVL_PUBLIC_GATE_ENABLED=1；有 IP 限速与全局日预算，忙时返回"稍后再试"）。能力边界：响应不含 decisionUrl、无 get_decision 读回（tools/list 只暴露 assess）、无工作区缓存/审计/outcome 回填。适合"先试后注册"的现场评估；要完整能力请创建工作区 key。

先把 key 放进启动环境（如 ~/.zshenv 中 export PVL_GATE_API_KEY=...，或 secret manager 注入），再让 MCP 配置按名引用——两家客户端都支持配置内环境变量展开，明文不落配置文件、不进 argv：

安全边界：这是 ProjectValueLab 的入站机器凭据（N1，工作区级、可吊销、有限速与审计），不是 InfiniSynapse 上游 key——上游 key 永远只在 PVL 服务端。本 MCP server 不落盘、不回显 key（输出边界另有强制脱敏兜底）。

Claude Code

项目级或用户级 .mcp.json（${VAR} 展开语法，来自启动 Claude Code 的 shell 环境）：

{
  "mcpServers": {
    "pvl-gate": {
      "command": "pvl-gate-mcp",
      "env": {
        "PVL_GATE_URL": "${PVL_GATE_URL:-https://pvl.example.com}",
        "PVL_GATE_API_KEY": "${PVL_GATE_API_KEY}"
      }
    }
  }
}

（claude mcp add 的 --env KEY=value 会把明文放进 argv/shell history，不要用它传 key。）

Cursor

~/.cursor/mcp.json（或项目 .cursor/mcp.json；Cursor 的展开语法是 ${env:NAME}）：

{
  "mcpServers": {
    "pvl-gate": {
      "command": "pvl-gate-mcp",
      "env": {
        "PVL_GATE_URL": "${env:PVL_GATE_URL}",
        "PVL_GATE_API_KEY": "${env:PVL_GATE_API_KEY}"
      }
    }
  }
}

注意：GUI 启动的桌面应用不一定继承 .zshrc 里的变量；变量放 ~/.zshenv 或系统级环境，或从已 export 的终端启动客户端。

与 Endor 类扫描 MCP 的差异（定位声明）

Endor Labs / SCA 类 MCP 的核心是仓库清点扫描：遍历依赖清单，报告漏洞/许可清单，输出面向修复。本 MCP 是决策服务，差异在四点：

1. 对象不同：单个"待引入"的依赖坐标（引入前拦截点），不是已有仓库的全量清单。
2. 输出不同：三态裁决（GO/VALIDATE/DROP）+ hardGates + 证据 + 模板化解释 + 可分享/可审计的 decisionUrl，不是漏洞列表。决策带 policyVersion，同一坐标在策略变更后会产生新决策。
3. 机制不同：确定性规则（OSV + deps.dev SPDX 许可表达式 + registry 采用度），无 LLM 参与裁决；同输入同输出、可缓存（命中 <1s）、OSV 新事件主动失效。
4. 闭环不同：决策进组织记忆——6.7 GateCallRecord 回填 outcome（听劝/后悔率），进 B3 校准面板；扫描器没有"决策后来对不对"的追踪。

两者互补：清点存量用扫描器，引入增量用本门禁。

版本与发布

• 版本号策略（0.x）：0.MINOR.PATCH——工具契约/行为变更升 minor，修 bug 升 patch；0.x 期间 minor 可含不兼容变更（发布说明中明示）。服务端决策规则有独立的 policyVersion/ruleVersion，不随本包版本走。
• 版本号随 package.json（当前 0.1.0），pvl-gate-mcp --version 可查。
• 本地验证：bash scripts/gate-mcp-verify.sh（构建 → pack → 临时目录安装 → --version + stdio 会话冒烟）。
• 对外发布到 MCP 注册生态（npm 公网 / MCP registry）是 outward-facing 动作，材料就绪后须经人工确认再执行。 为防误发布，package.json 带 "private": true（不影响 pack/本地安装，只拦 npm publish）；经人工确认对外发布时才有意移除。发布材料清单见 docs/product/gate-release/2026-07-22-gate-release-checklist.md。