103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# 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)
|