2026-09-02 16:39:26 +08:00

3.7 KiB
Raw 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 防护和错误脱敏。

参考: