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

103 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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="<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` 作为项目配置,内容如下:
```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)