Model Context Protocol · 知识检索

轻易云知识 MCP Server

面向 AI Agent 的电商财务对账专家知识库 MCP 服务：538 条生产验证的知识原子，覆盖 12 个财务域、10 个平台与 17 个客户案例。Agent 可检索、定位并取得带 Git 可追溯引用的证据，再由自己生成答案；其中 82 条通用方法论与财税准则已公开，平台操作手册与客户案例需授权访问。一个无状态 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://qeasy.cloud/api/mcp —— MCP Streamable HTTP（无状态模式）承载 JSON-RPC 2.0。GET/DELETE 返回 405，不维护会话。

认证可选：不传 Authorization 为匿名（每 IP 10 次工具调用/天，仅 public 知识）；传 `Authorization: Bearer qk_live_...` 为 standard Key（10 次/天，可在 /account 自助创建）或 authorized Key（不限量 + restricted 知识，由轻易云后台授权）。

推荐顺序：initialize → tools/list → knowledge_domains（免配额）→ knowledge_search → knowledge_fetch(citation#atomId)。

Claude Desktop / Cursor — mcp.json

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

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

# 1) handshake
curl -s https://qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2) discover tools (schemas + descriptions)
curl -s https://qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3) search public knowledge (anonymous, no key required)
curl -s https://qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"knowledge_search","arguments":{"query":"费用按收入占比分摊什么时候合理","granularity":"atom","includeMeta":true}}}'

# 4) authorized key: search restricted playbooks and fetch one atom
curl -s https://qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer qk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"knowledge_fetch","arguments":{"citation":"docs/knowledge/platforms/jdpop.md#KA-PARSE-JDPOP-HEADER-001"}}}'

响应与引用契约

工具只返回检索证据，不生成答案；调用方 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 源路径 + 原子锚点）。请在答案中标注该值，稳定且可审计。
granularity="atom" 为每个知识原子返回一条命中，适合阈值、报错码、边界规则等专家场景；granularity="doc" 将文档折叠为最佳命中，更省 token。
fetch 成功返回正文（或单原子）及 citation、product/type、visibility、docMeta；maxChars 截断时返回 truncated:true 与 originalChars。
quota { remaining, resetAt } 仅对匿名/standard 返回；authorized 不限量不返回。
空结果不是错误：返回 hits:[] + suggestions。若无结果，通常是该主题属于 restricted（需授权 Key）或超出对账知识范围。

访问分级与配额

两级三态。注册本身不提额——只有明确授权才会放大额度和知识范围。

配额按 Asia/Shanghai 每日 00:00 重置；第 11 次计费调用返回 -32029，data.retryAfter 为秒数、data.resetAt 为重置时间。knowledge_domains、initialize、tools/list 不扣配额。

每次工具调用都经过认证、SQL 层可见性过滤、配额检查并写入审计（工具、身份级别、Key 前缀、IP、耗时、状态；绝不记录明文 Key 或文档正文）。

匿名 — 无需 Key

每 IP 每天 10 次工具调用，仅 public 知识（当前 82 条：费用核算/分摊、平台接入方法论、收入确认、增值税与发票）。适合先试用端点与工具 schema。

Standard — 自助 Key

在 /account 创建（每人最多 5 个有效 Key），每 Key 每天 10 次，仅 public 知识。用于稳定身份与 MCP 客户端固定凭据。

Authorized — 轻易云授权

不限量调用 + 全部 538 条知识（public + restricted：平台操作手册、差异标签、客户案例等），可按产品/类型收窄范围并设有效期。通过轻易云后台开通，联系我们申请。

错误码与限制

-32001 UNAUTHORIZED —— Key 无效/已吊销/已过期（HTTP 401）。请更换 Bearer Token。
-32403 FORBIDDEN —— 文档为 restricted 且当前身份未授权；data.upgradeHint 给出下一步。
-32029 RATE_LIMITED —— 当日配额用尽；data.retryAfter（秒）与 data.resetAt（沪时区零点）。
-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 对象（不支持批量）。
知识范围：当前为轻易云电商财务对账语料（43 篇 / 538 原子），其中 public 82 条；集成平台知识与业务写工具在 Roadmap 中；public 知识域会随入库进度出现在 knowledge_domains。

路线图

本端点刻意保持克制：它是知识检索引擎，不是通用业务 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 知识库与不限量调用。

获取 API Key 申请授权访问