轻易云
注册体验
Model Context Protocol · 知识检索

轻易云知识 MCP Server

面向 AI Agent 的轻易云知识 MCP 服务:一个端点覆盖两条产品线的持续同步知识库——电商财务对账(12 个知识域、平台专题与客户案例,其中通用方法论与财税准则已公开)与数据集成平台(K1 操作运维 / K2 接口元数据 / K3 方案设计三大类,分层公开)。Agent 可检索、定位并取得带 Git 可追溯引用的证据,再由自己生成答案;公开知识 Standard 即可检索,平台手册与客户案例需授权访问。一个无状态 HTTP 端点:POST /api/mcp。

现已上线:三个知识工具

工具清单可在运行时通过 MCP `tools/list` 获取,无需 SDK 或生成客户端;任何兼容 MCP 的 Agent(Claude、Cursor、自研)都可直接用 JSON-RPC 接入。

knowledge_search — 找证据

对结算对账知识库做向量 + 关键词混合检索。参数:query(必填);product、type 过滤;limit(1–20,默认 8);granularity('doc' 默认每文档一条,'atom' 每个 KA-* 知识原子一条);includeMeta(返回域名/平台等元数据)。返回带 citation、score、visibility 的排序命中。

knowledge_fetch — 取原文

按 docId、citation(sourcePath#atomId)或 atomId 取整篇文档或单个知识原子;maxChars 可控制返回体积。受限文档在未授权时返回 -32403。

knowledge_domains — 检索前路由

列出当前身份可见的 product × type 知识域及文档数,不消耗配额——建议检索前先调用,确定该去哪找。

快速接入

端点为无状态服务:每个请求自带认证,天然适配 serverless 与多实例部署。

端点:POST https://www.qeasy.cloud/api/mcp —— MCP Streamable HTTP(无状态模式)承载 JSON-RPC 2.0。GET/DELETE 返回 405,不维护会话。

所有 MCP 调用都必须携带 Key。Agent 先调用 /api/v1/agent-registrations/challenge,完成 SHA-256 PoW 后提交 /api/v1/agent-registrations,自动获得 Standard Key(20 次/天、public 知识);无需手机号、不发 session、不进入销售线索。人类仍从 /register 注册并自动获 Key。

推荐顺序:注册 Agent → initialize → tools/list → knowledge_domains → knowledge_search → knowledge_fetch(citation#atomId)。

Claude Desktop / Cursor — mcp.json

{
  "mcpServers": {
    "qeasy-knowledge": {
      "url": "https://www.qeasy.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer qk_live_YOUR_KEY"
      }
    }
  }
}

原生 JSON-RPC — initialize / tools/list / 检索 / 取原子

# 1) request an agent registration challenge
curl -s -X POST https://www.qeasy.cloud/api/v1/agent-registrations/challenge
# => save challengeId and difficulty from data

# 2) solve sha256(challengeId + ':' + nonce) proof-of-work
export CHALLENGE_ID='paste-challenge-id'
export DIFFICULTY='18'
python3 -c 'import hashlib,os
cid=os.environ["CHALLENGE_ID"]; bits=int(os.environ["DIFFICULTY"]); n=0
while True:
 h=hashlib.sha256(f"{cid}:{n}".encode()).digest()
 if int.from_bytes(h[:4],"big") >> (32-bits) == 0: print(n); break
 n+=1'
# => save printed nonce

# 3) register the agent; plaintext key is returned only once
curl -s https://www.qeasy.cloud/api/v1/agent-registrations \
  -H 'content-type: application/json' \
  -d '{"name":"My Agent","framework":"custom","version":"1.0","challengeId":"paste-challenge-id","nonce":"paste-nonce"}'

# 4) call MCP with the Standard key (20 public-knowledge calls/day)
curl -s https://www.qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer qk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

curl -s https://www.qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer qk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"knowledge_search","arguments":{"query":"费用按收入占比分摊什么时候合理","granularity":"atom","includeMeta":true}}}'

响应与引用契约

工具只返回检索证据,不生成答案;调用方 Agent 负责组织答案,并必须标注引用。

  • 检索命中:{ docId, title, excerpt(≤500 字), score, product, type, citation, url, visibility, atomId?, docMeta? } —— 命中 KA-* 原子时返回 atomId;includeMeta=true 时返回 docMeta。
  • citation 格式按产品域区分:对账知识 = `docs/knowledge/<file>.md#KA-...`(Git 源路径 + 原子锚点);集成平台知识 = `docs/knowledge/<doc>#节标题`(原子粒度时)或 `#chk_...`(chunkId)。请在答案中标注该值,稳定且可审计。
  • 响应形态:`content[0].text` 是 Markdown 摘要(给人/模型阅读);机器可读的结构化数据在 `result.structuredContent`(hits/page/quota/citation 等字段),程序请勿解析 Markdown。
  • granularity="atom" 为每个知识原子(集成平台为每个 chunk)返回一条命中,适合阈值、报错码、边界规则等专家场景;granularity="doc" 将文档折叠为最佳命中,更省 token。
  • fetch 成功返回正文(或单原子)及 citation、product/type、visibility、docMeta;maxChars 截断时返回 truncated:true 与 originalChars。
  • quota { remaining, resetAt } 仅对 standard 返回;authorized 默认不限每日次数不返回。完整缓存 HIT 不扣日配额和分钟额度,MISS/COALESCED/BYPASS 照常计费。
  • 空结果不是错误:返回 hits:[] + suggestions。若无结果,通常是该主题属于 restricted(需授权 Key)或超出知识范围。

访问分级与配额

两类注册、两档权限。注册只授予 Standard;restricted 仍需明确授权。

日配额按 Asia/Shanghai 每日 00:00 重置;第 21 次非缓存计费调用返回 HTTP 429 + -32029,errorKind=daily_quota。分钟超限 errorKind=minute_rate_limit。knowledge_domains、initialize、tools/list 不扣日配额。

standard 默认 120 次/分钟,authorized 默认 600 次/分钟;每次工具调用都经过认证、SQL 层可见性过滤与审计,绝不记录明文 Key 或文档正文。

Agent 注册 — 无手机号

通过挑战 + SHA-256 PoW 开放注册,带 IP 限额、失败审计和数据库幂等。Agent 不需要手机号,不创建网页 session,不进入 CRM 或销售线索。

Standard — 注册自动颁发

人类或 Agent 注册后自动获得首个 Key;/account 可继续创建(每人最多 5 个有效 Key)。每账号每天 20 次,全部 Standard Key 共享,仅 public 知识。

Authorized — 轻易云授权

默认不限每日次数 + 全部授权知识(public + restricted),可按产品/类型收窄范围并设有效期。通过轻易云后台开通,联系我们申请。

两种使用范式

同一个端点服务两种工作流,Agent 按任务选择(M24 蓝图实测最佳实践)。

  • 问答:knowledge_search 取 top-k → knowledge_fetch(citation#section) 取单段证据;excerpt ≤500 字,token 友好。
  • 方案蓝图:先收敛(product + scenario + category + platform;platform 接受路径 slug / 上游 code / 中文厂商名,大小写不敏感,如 kingdee-cloud、Kingdee.Cloud、金蝶云星空)→ 再按需 fetch 关键节(字段映射 / 增量 / 风险)而非整篇。对象/配对级知识请用标识符(接口名/单据名/字段名)提问;「推不出的字段」以 pairs 文档 §7「无主值」标注为准。
  • 诚实边界:语料对「推不出的字段」显式标注(V 类/无主值),请照标不编造;restricted 的案例与方案集需 authorized Key。

错误码与限制

  • -32001 UNAUTHORIZED —— 未提供 Key、Key 无效/吊销/过期或主体被禁用(HTTP 401);按返回的人类/Agent 注册指引进门。
  • -32403 FORBIDDEN —— 文档为 restricted 或超出 Key scope;data.upgradeHint 给出下一步。
  • -32029 RATE_LIMITED —— HTTP 429;errorKind=daily_quota 或 minute_rate_limit,附 Retry-After 与 RateLimit 头。
  • -32602 INVALID_PARAMS —— 参数校验失败;message 指出具体字段(如 query 为空、limit>20、atomId 格式错误)。
  • -32601 METHOD_NOT_FOUND —— 未知 JSON-RPC 方法;-32600 INVALID_REQUEST —— 缺少 method 或批量数组;-32700 PARSE_ERROR —— 请求体不是合法 JSON(HTTP 400)。
  • -32603 INTERNAL_ERROR —— 服务端异常,请退避重试。请求体必须是单个 JSON 对象(不支持批量)。
  • 知识范围:对账与集成平台双域语料持续同步,文档与原子实时规模以 knowledge_domains 为准;公开知识随定级评审滚动扩面。数据集成平台检索支持 scenario(S1/S2/S3,缺省 S2)与 category(K1/K2/K3)过滤;平台操作 MCP(39 工具)为另一套服务,见 /skill/datahub。业务写工具在 Roadmap 中。

能力目录

官网 MCP 能力统一目录(拆分判据 = Agent 任务是否不同)。知识检索共用本端点、按产品域区分;各产品的操作类 MCP 独立部署、官网只做指引。

数据集成平台知识 · /mcp/datahub-knowledge

K1 平台操作与运维 / K2 平台接口与元数据 / K3 集成方案设计模式三大类;product=data-integration 检索,scenario 与 category 硬过滤,citation=源路径#节。SOL/CASE/FAIL 三层 restricted。

对账知识 · /mcp/reconciliation-knowledge

12 个知识域、平台专题与客户案例(通用方法论/财税准则已公开)。对账系统的操作 MCP 为完全私有化部署,官网当前仅提供知识库。

数据集成平台操作 MCP · /skill/datahub

DataHub Platform MCP:39 个 Tool(资产/方案/脚本/审计),租户一键授权、sh-xxx 密钥。公有云端点 pro-service.qliang.cloud/mcp;私有化部署由客户域名自描述。

R18 检索与运行保障

  • search 新增 domain/platform 过滤、cursor 稳定分页与 minScore;score 统一为 0~1,并返回 vector/keyword/rrf 分项和 matchedOn。离题查询返回 hits:[],不再强行给无关证据。
  • initialize 与 tools/list 动态读取当前身份可见规模;knowledge_domains 增加 stats 和 domain/platform facets;三工具均提供 outputSchema。
  • 远程向量化和检索结果均有 TTL 缓存,相同并发请求合并回源;知识同步后按修订号失效。响应带 X-Qeasy-Cache 与 Server-Timing。
  • 所有响应带 X-Request-ID 并可关联审计;支持 CORS/OPTIONS、401 WWW-Authenticate、64 KiB 包体上限,以及 standard 120/min、authorized 600/min 的 RateLimit/Retry-After 背压。
  • 健康检查:GET /api/v1/mcp/health 真实探测 PG、Redis、embedding;运营指标:GET /api/v1/mcp/metrics(独立 Bearer Token,无 PII)。

路线图

本端点刻意保持克制:它是知识检索引擎,不是通用业务 API。以下能力已规划但**当前不可用**,请勿提前对接。

  • connector.invoke / connector.describe —— 通过 schema 校验参数调用预置的 ERP、电商、CRM、WMS、MES 连接器。
  • pipeline.run / pipeline.status —— 触发并监控数据集成管线。
  • reconciliation.query / reconciliation.explain / reconciliation.draft —— 查询对账结果、追溯差异、生成待人工确认的凭证草稿。

给你的 Agent 补上电商财务对账专家

在 /account 免费领取 standard Key 即可试用 public 知识;申请 authorized Key 可解锁全部 restricted 知识库与不限量调用。

Qeasy Knowledge MCP Server — 对账 + 集成平台双域知识库 · AI Agent 检索接口 | 轻易云