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

90 lines
3.7 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 防护和错误脱敏。
参考:
- [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)