# 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: ```bash export MCP_AUTH_TOKEN="" 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` 作为项目配置,内容如下: ```jsonc { "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。 ## 验证 ```bash 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,未写入真实凭据。 参考: - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [MCP Streamable HTTP 规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) - [WorkBuddy Enterprise MCP 使用文档](https://cloud.tencent.cn/document/product/1831/137039)