2026-09-02 17:10:56 +08:00

4.6 KiB
Raw Permalink Blame History

DEMO-012 MCP Gateway 使用说明

范围

DEMO-012 提供独立的 Enterprise Knowledge MCP Gateway,通过标准 Streamable HTTP 暴露一个 只读工具:search_knowledge。Gateway 直接复用 API 进程使用的 SearchService 组合,不复制 Dense Retrieval、Reranker 或 Source Enrichment 逻辑。

当前 Demo 只建立认证和身份传递边界:一个运行时注入的专用 Bearer Token 映射到一个 user/service identity,并且只有 knowledge:search scope。它不是共享超级管理员 Token,也不 代表 V1 OAuth、Document ACL 或完整 MCP P0 工具已经完成。

配置

必须通过运行环境提供至少 32 字符的随机 Token:

export MCP_AUTH_TOKEN="<runtime-secret-with-at-least-32-characters>"
make run-mcp

默认地址为 http://127.0.0.1:8766/mcp。除现有数据库、BOS、Embedding、Vector 和 Reranker 配置外,Gateway 支持:

变量 默认值 说明
MCP_HOST 127.0.0.1 监听地址;本地默认不暴露到其他网卡
MCP_PORT 8766 Gateway 端口
MCP_PATH /mcp Streamable HTTP 单一端点
MCP_PUBLIC_URL http://127.0.0.1:8766/mcp MCP Resource Server URL
MCP_ISSUER_URL http://127.0.0.1:8766 Demo Token 的身份颁发方标识
MCP_CLIENT_ID workbuddy-enterprise MCP Client 类型标识
MCP_SERVICE_IDENTITY workbuddy-demo 传入业务边界的服务身份
MCP_REQUIRED_SCOPE knowledge:search Tool 所需最小 scope
MCP_ALLOWED_HOSTS 仅本机/test DNS rebinding Host allowlist,JSON 数组
MCP_ALLOWED_ORIGINS 仅本机 Origin allowlist,JSON 数组

远程部署必须使用 TLS 反向代理,并把公开域名加入 MCP_ALLOWED_HOSTS;有 Origin 的客户端还 必须显式配置 MCP_ALLOWED_ORIGINS。Token、真实域名和内部 Endpoint 不得提交 Git。

WorkBuddy / CodeBuddy 配置

WorkBuddy Enterprise 官方客户端支持 type: "http"、远程 URL、自定义 Header 和环境变量 展开。可复制 deploy/workbuddy-mcp.example.json 作为项目配置,内容如下:

{
  "mcpServers": {
    "enterprise-knowledge": {
      "type": "http",
      "url": "${EKP_MCP_URL:-http://127.0.0.1:8766/mcp}",
      "headers": {
        "Authorization": "Bearer ${EKP_MCP_TOKEN}"
      },
      "description": "企业知识检索"
    }
  }
}

只提交包含环境变量占位符的配置;EKP_MCP_TOKEN 必须由每个运行环境安全注入。连接后应只 发现 mcp__enterprise_knowledge__search_knowledge 一个工具。

安全和错误语义

  • 缺失或错误 Token 返回 401,缺少 scope 返回 403;
  • 未批准 Host 返回 421,未批准 Origin 返回 403;
  • Query 长度和 top_k 在 MCP schema 层校验;
  • 预期业务错误返回安全 Tool Error;未知 Provider/数据库错误收敛为 knowledge search failed;
  • MCP 输出和 Gateway 日志不得包含 Token、Provider Endpoint、数据库表名、模型名或 Index Profile。

验证

uv run pytest tests/unit/test_mcp_auth.py tests/unit/test_mcp_search.py
uv run pytest tests/integration/test_mcp_server.py

集成测试使用官方 MCP Python Client 通过 Streamable HTTP 完成 initialize、tools/list 和 tools/call,并使用与 WorkBuddy 相同的 Bearer Header 配置验证身份传递、无结果、参数错误、 认证失败、Origin 防护和错误脱敏。

WorkBuddy 现场验收记录

2026-09-02 使用 WorkBuddy Desktop 5.3.14 自带的 CodeBuddy CLI 2.115.0 完成兼容性 验收。客户端直接加载 deploy/workbuddy-mcp.example.json,健康检查为 Connected;工具 发现结果只有 mcp__enterprise-knowledge__search_knowledge,随后以字符串 query 和 top_k=1 完成 Tool 调用并读取结构化 filename、section、content 等来源字段。

现场验收使用 DEMO-012 的真实 Gateway、Bearer 验证、service identity 传递、输入 Schema 和 Tool 注册代码。为避免外部数据库与模型波动掩盖客户端兼容性,检索应用使用确定性验收返回; 真实 Provider 检索链路由 ARCH-006 的受控验收负责。非交互 CLI 需要批准 MCP Tool 调用, 本次只在单次会话中允许 DeferExecuteTool,没有永久启用跳过权限。测试结束后已删除临时 MCP 配置并停止本地 Gateway,未写入真实凭据。

参考: