56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# MCP Contract
|
||
|
||
P0 business tools:
|
||
|
||
- `search_knowledge`
|
||
- `get_document`
|
||
- `get_document_section`
|
||
- `get_source`
|
||
- `list_knowledge_bases`
|
||
|
||
Every request maps to a user/service identity and uses the same authorization/application services as REST. Do not expose OceanBase Vector, BOS, model names, parsers or other infrastructure choices.
|
||
|
||
## Demo priority slice(DEMO-012,已实现)
|
||
|
||
`DEMO-012` 已提升为当前最高实现优先级。首个可运行 Gateway 只注册
|
||
`search_knowledge`,其输入与 `/api/v1/search` 对齐:
|
||
|
||
```json
|
||
{
|
||
"query": "产品A退款周期是多少?",
|
||
"top_k": 5
|
||
}
|
||
```
|
||
|
||
输出保留业务来源字段:`document_id`、`filename`、`page`、`section`、`chunk_id`、`content`
|
||
和排序分数。Gateway 必须复用现有 Search Service 或正式 REST API,不得复制检索、来源补全
|
||
或排序逻辑。
|
||
|
||
Demo 验证也必须建立 user/service identity 映射边界,禁止使用共享超级管理员 Token。由于
|
||
Document ACL 尚未进入 Demo Scope,`DEMO-012` 只能证明身份传递、认证拒绝和业务服务复用,
|
||
不能声称完成 V1 ACL 授权闭环。错误响应和日志不得包含 Provider Endpoint、凭据、数据库表名
|
||
或模型名。
|
||
|
||
验收至少覆盖:MCP 工具发现、参数校验、成功检索、无结果、认证失败、安全错误收敛,以及
|
||
WorkBuddy Enterprise 的一次端到端调用。其余 P0 tools 继续留在完整 V1 `EKP-071`。
|
||
|
||
实现使用独立 Streamable HTTP Gateway,默认端点为 `http://127.0.0.1:8766/mcp`。请求必须
|
||
携带 `Authorization: Bearer <token>`;Token 只从运行环境读取,并映射为显式 service identity
|
||
和 `knowledge:search` scope。当前静态 service credential 是 Demo 兼容层,不替代 V1 OAuth、
|
||
ACL 或用户委托授权。
|
||
|
||
公开错误边界:缺失/无效 Token 为 HTTP `401`,scope 不足为 `403`;Tool 参数不合法返回 MCP
|
||
参数错误;检索运行失败只返回 `knowledge search failed`。Host/Origin allowlist 默认只允许
|
||
本机,远程部署必须显式注入公开域名。
|
||
|
||
## 当前公共知识库部署边界(PLAN-002)
|
||
|
||
集群阶段仍只暴露只读 `search_knowledge`,并为 WorkBuddy 配置稳定的 HTTPS MCP 地址。
|
||
Credential 由 Kubernetes Secret 在服务端运行时注入,客户端只保存管理员分发的最小
|
||
`knowledge:search` Token;Pod 重启或滚动升级不得要求重新生成配置。公共知识域不等于匿名
|
||
访问或超级管理员身份,未来引入非公共知识前必须升级为用户委托身份与 ACL-aware Search。
|
||
|
||
DEPLOY-003 的远程验收必须从最终 HTTPS 地址只发现 `search_knowledge` 并完成一次真实、有来源
|
||
结果的调用。Gateway 失败日志只记录固定事件名,不写请求 Query、异常正文、Provider Endpoint
|
||
或 Token;具体请求量与 Pod 可用性由集群入口/Kubernetes 指标补充,当前不新增 MCP 业务 Tool。
|