MCP 集成概览

GraphForge 提供标准 Model Context Protocol Server，外部 LLM Agent（Claude Desktop / Cursor / 自研 Agent）可以不走 REST，通过 MCP 协议直接调 9 个 tools。

何时用 MCP vs REST

场景	走 REST	走 MCP
网页 / 后端服务集成	✅	✗
Claude Desktop / Cursor 让 LLM 调用	✗	✅
自研 Agent（Anthropic SDK / OpenAI 函数调用）	可（手写 OpenAPI 包装）	✅（用现成 MCP Client SDK）
不需要 LLM，纯数据集成	✅	✗

9 个 Tools

Tool	来源	一句话用途
`query_knowledge`	v1	自然语言查图谱
`get_entity_info`	v1	拿单个实体详情
`get_entity_relations`	v1	拿实体的关系网络（含 direction/type 过滤）
`search_entities`	v1	实体模糊搜
`get_provenance`	v1	数据血缘溯源
`compute_metric`	v2	算指标值（绕过 RAG 直查 SQL，错填 metric_id 给同义建议）
`get_metric_lineage`	v2	拿血缘图（mermaid / json / table 3 格式）
`analyze_root_cause`	v2	RCA Agent 5-phase 编排（compute + lineage + Critic+Researcher）
`echo`	spike	验证 MCP 链路通（生产可忽略）

完整 schema（inputSchema / outputSchema / description）见 /api/mcp-tools.json。

Claude Desktop 接入

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "graphforge": {
      "command": "/path/to/graphforge/backend/venv/bin/python3",
      "args": ["-m", "app.mcp.v2.server"],
      "cwd": "/path/to/graphforge/backend"
    }
  }
}

重启 Claude Desktop → 在 Chat 输入 "用 graphforge 列出当前所有图谱" → Claude 会自动选 query_knowledge / search_entities 调用。

Cursor / 自研 Agent 接入

参考 modelcontextprotocol.io/clients。GraphForge 走标准 stdio / SSE / streamable_http 传输，任何符合 MCP 1.0 协议的 client 都能接。

涉密客户加固

通过 5 个 SMOKE_* 环境开关启用涉密 Profile（不影响协议层）：

SMOKE_AUDIT_LOG_ENABLED=true — 所有 RPC 入审计表
SMOKE_AUTH_MODE=strict — JWT TTL 30min + fingerprint + MFA stub
SMOKE_PII_REDACTION=on — 按用户密级脱敏 17 类 PII 字段
SMOKE_MCP_TRANSPORT=mtls — 仅 SSE-over-mTLS（部署期实施）
SMOKE_EMERGENCY_KILL_SWITCH=on — admin /admin/mcp/kill-all-sessions 紧急断所有 session

详见 admin /admin/mcp/audit-log 和 /admin/mcp/kill 页面（仅 admin）。

错误码

MCP RPC 错误统一通过 MCPErrorCode 枚举返（15 种），常见：

Code	含义
`INVALID_INPUT`	参数不符 inputSchema
`METRIC_NOT_FOUND`	metric_id 不存在（会附 `suggestion` 同义候选）
`MISSING_BINDING`	metric 没建物理绑定
`UNAUTHORIZED`	License / JWT / API Key 校验失败
`RATE_LIMITED`	触发速率限制
`INTERNAL_ERROR`	后端异常

REST 等价 API

部分 MCP tools 在 REST 端也有等价：

compute_metric → POST /api/graphs/{id}/metrics/{metric_id}/execute
get_metric_lineage → GET /api/graphs/{id}/metrics/{metric_id}/lineage
analyze_root_cause → POST /api/graphs/{id}/rca

但 query_knowledge / get_entity_relations 等查询类 tools 是 MCP 专有（REST 端没有完全等价的封装）。