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

2.0 KiB
Raw Permalink Blame History

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 对齐:

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