knowledge-platform/docs/api/MCP_CONTRACT.md

56 lines
2.9 KiB
Markdown
Raw Permalink 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.

# 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。