MCP Server 设计（@dependfix/mcp）

通过 Model Context Protocol 将 dependfix 的能力暴露给 AI 编程助手（Claude、Copilot、Cursor 等），实现 CLI + Skills 自动化闭环。

---

1. 定位

@dependfix/mcp 是一个 MCP Server，运行后向 AI 助手注册 4 个 tool。AI 助手可通过工具调用直接拉取告警、执行修复、获取报告，无需用户手动输入 CLI 命令。

用户："检查这个仓库的安全告警"
  → AI Agent 调用 mcp_dependfix_fetch_alerts
    → 返回标准化告警列表
  → AI Agent 调用 mcp_dependfix_scan
    → 执行修复流程
  → AI Agent 返回结构化的修复摘要

---

2. Tool 清单

Tool	功能	输入 Schema	输出
fetch_alerts	拉取 Dependabot 告警	repo: string, severity?: string	NormalizedSecurityAlert[]
fix_dependency	修复单个依赖	repo: string, packageName: string, targetVersion: string	DependencyFixResult
run_scan	执行完整扫描修复	repo: string, mode?: 'report-only' | 'fix', severity?: string	RunResult
get_last_report	读取最近一次 JSON 报告	—	RunResult | null

---

3. 架构

┌─────────────────────────────────────┐
│  AI 助手 (Claude / Copilot / Cursor) │
└──────────────┬──────────────────────┘
               │ JSON-RPC (stdio)
┌──────────────▼──────────────────────┐
│  @dependfix/mcp                     │
│  ├── server.ts    # MCP Server 启动 │
│  ├── tools/       # 4 个 tool 实现  │
│  └── transport.ts # stdio 传输层    │
└──────────────┬──────────────────────┘
               │ 直接调用（无网络）
┌──────────────▼──────────────────────┐
│  @dependfix/core  # 告警模型/过滤/报告 │
│  dependfix/cli    # 编排/app 逻辑   │
└─────────────────────────────────────┘

3.1 与 CLI 的关系

packages/cli（dependfix）
  → runCli() / DependfixApp
  → 解析 CLI args → resolveRuntimeConfig → run()

packages/mcp（@dependfix/mcp）
  → 直接调用 DependfixApp（程序化接口）
  → tool handler 构造 RuntimeConfig → new DependfixApp({ config }).run()

MCP Server 不依赖 CLI args 解析，直接走程序化 API。这要求 DependfixApp 的接口已经足够干净（T505 解耦后满足）。

3.2 依赖

依赖	版本	用途
@modelcontextprotocol/sdk	^1.x	MCP Server 框架
@dependfix/core	workspace:*	告警模型与报告
dependfix	workspace:*	CLI 编排逻辑

---

4. Tool 实现要点

4.1 fetch_alerts

{
  name: 'fetch_alerts',
  description: '拉取指定仓库的 Dependabot 安全告警',
  inputSchema: {
    repo: { type: 'string', description: 'owner/repo' },
    severity: { type: 'string', enum: ['critical','high','medium','all'] },
  },
}

4.2 run_scan

{
  name: 'run_scan',
  description: '对目标仓库执行 dependfix 扫描并修复',
  inputSchema: {
    repo: { type: 'string', description: 'owner/repo' },
    mode: { type: 'string', enum: ['report-only', 'fix'], default: 'report-only' },
    severity: { type: 'string', default: 'high' },
  },
}

注意：fix 模式会修改文件，应以 report-only 为默认。

4.3 认证

MCP Server 本身不管理凭据。GITHUB_TOKEN 和 AI_API_KEY 从环境变量读取：

mcpServer.connect(transport)
  → tool handler 读取 process.env.GITHUB_TOKEN
  → 传入 DependfixApp 的 RuntimeConfig

4.4 错误处理

场景	行为
Token 缺失	返回 { ok: false, error: "GITHUB_TOKEN not set" }
API 限流	返回限流信息，建议稍后重试
仓库无权访问	返回 403 错误详情

---

5. 集成方式

用户通过 AI 助手的 MCP 配置文件添加：

{
  "mcpServers": {
    "dependfix": {
      "command": "npx",
      "args": ["@dependfix/mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

---

6. 与 Skills 的关系

MCP 提供底层 tool 能力，Skills 提供高层编排：

MCP Tool: fetch_alerts, run_scan, fix_dependency
     ↑
Skill: security-alert-remediator
     ↑
Agent: 用户对话 → Skill 编排 → MCP 执行 → 报告

当前已有的 security-alert-remediator skill 将来可通过 @dependfix/mcp 的 tool 直接调用，代替手写 CLI 命令。

---

7. 里程碑

阶段	内容
M6 T606	MCP Server 骨架 + fetch_alerts / get_last_report tool
M6 T607	run_scan / fix_dependency tool + 与 CLI 互操作验证
M7 T706	MCP Server 发布 npm + 集成到 security-alert-remediator skill