# @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）。

## 安装与配置

```bash
# 仓库根目录：打包（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 环境）：

```json
{
  "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}`）：

```json
{
  "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`。