knowledge-platform/docs/api/MCP_CONTRACT.md
2026-09-02 16:39:26 +08:00

45 lines
2.0 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 默认只允许
本机,远程部署必须显式注入公开域名。