MCP Server 接入与工具参考

OpenAPI 不覆盖 MCP 协议。通过标准 Streamable HTTP 端点 /mcp/,让 Cursor、Claude Code 或自研智能体直接调用 ApeMind 的混合检索、原文溯源、知识图谱、文档对比与受控外部连接能力。

接入地址与鉴权规则

客户端接入示例

Claude Code

claude mcp add --transport http apemind https://apemind.ai/mcp/ \
  --header "Authorization: Bearer ${APEMIND_API_KEY}"

Cursor(.cursor/mcp.json)

{
  "mcpServers": {
    "apemind": {
      "url": "https://apemind.ai/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:APEMIND_API_KEY}"
      }
    }
  }
}

curl(Streamable HTTP JSON-RPC 最小闭环)

# 1. 初始化会话并提取 Mcp-Session-Id(如服务端返回)
curl -i -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl-probe", "version": "1.0.0"}
    }
  }'

# 2. 列出当前身份可用的全部工具(以当次 tools/list 的 JSON Schema 为准)
curl -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

# 3. 调用 search_knowledge 检索指定知识库
curl -sS -X POST "${APEMIND_BASE_URL}/mcp/" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_knowledge",
      "arguments": {
        "collection_id": "'"${KB_ID}"'",
        "query": "合同解除条件",
        "top_k": 5
      }
    }
  }'

前置门槛(requires)与公共数据结构

tools/list 响应的注解里通过 requires 声明三档前置条件:workspace_access(已选定有效组织)、collection_access(对目标知识库有读权限,隐含 workspace_access)与 web_access(部署与身份允许公网出口)。超出数值上限的参数除标注「超出直接报错」外会自动收敛并在 *_applied 中返回实际值。

证据引用(EvidenceRef)与 search_knowledge 返回结构

全部 20 个内置工具清单

以下清单与后端注册表(aperag/mcp/registration.py)保持同步;实际可用工具受调用方 API Key 作用域或 Agent builtin_tools 白名单约束。完整字段 Schema 可直接读取 tools/list 或内置资源 apemind://usage-guide / apemind://usage-guide/en。

1. 目录与元数据探索

工具名 主要入参 用途与返回要点
list_collections query?, limit?, cursor? 列出当前组织内可读知识库(含只读市场订阅库)的 ID、标题与文档计数
list_documents collection_id, query?, limit?, cursor? 列出指定知识库内的文档清单、状态与解析版本
get_collection_metadata collection_id 查看知识库索引配置、语言、文档概览及图谱实体类型分布
get_document_metadata collection_id, document_id 查看单篇文档的章节目录(TOC)、页数/分块数、索引进度与解析版本

2. 检索、精确匹配与多模态分析

工具名 主要入参 用途与返回要点
search_knowledge collection_id, query, modes?, top_k?, excerpt_chars? 默认首选检索工具:默认融合 vector(含文字与图片)+ fulltext,传入 modes: ["vector","fulltext","graph"] 叠加图谱;同时返回 items、image_items、qa_items 与 modes_skipped
grep_documents collection_id, pattern, document_ids?, case_sensitive?, context_chars? 在解析后的 Markdown 正文中做字面/正则精确查找,适合编号、条款号、函数名与型号检索
diff_documents old, new, max_hunks? 对两篇文档(或同一文档的不同版本)生成结构化差异 Hunk,适合制度修订对比
analyze_knowledge_image collection_id, document_id, image_id, question 调用视觉模型针对知识库内提取出的图表、截图或公式做细粒度问答分析

3. 原文阅读与证据核对

工具名 主要入参 用途与返回要点
read_evidence_refs refs[], max_chars_per_ref? 批量把检索返回的 ref(含文本片段与 qa_items)展开为完整原文与上下文
read_document_chunks collection_id, document_id, chunk_ids[] / 窗口参数 按分块 ID 或前后邻接窗口顺序展开阅读,适合沿着 recommended_read 补全上下文
read_document collection_id, document_id, section_path? / 范围参数 按章节路径或字节/字符范围顺序通读单篇文档

4. 知识图谱探索

工具名 主要入参 用途与返回要点
lookup_entity collection_id, name 查询单个实体的定义、关系邻居及带 target_chunk_id 的 recommended_read
list_entities collection_id, entity_type?, query?, limit? 按实体类型或关键词浏览知识图谱节点
find_entity_paths collection_id, source_entity, target_entity, max_hops? 发现两个实体之间的跨文档多跳关联路径与支撑证据

5. 公网检索、受管函数与外部连接

工具名 主要入参 用途与返回要点
web_search query, limit? 公网搜索引擎查询(需 workspace_access + web_access)
web_read urls[], max_chars? 抓取并正文提取指定网页 URL(受 URL 数量与总字符预算上限约束)
list_functions query?, limit? 列出当前身份获授权调用的组织受管函数及其入参 Schema(默认关闭,需授权开启)
call_function function, input? 执行指定受管函数并返回结构化输出
list_connections connection?, limit? 省略 connection 时列出可用外部连接;传入连接 ID 或 slug 时返回该连接可调用的操作及 input_schema
invoke_connection connection, operation, arguments? 调用已授权的外部连接操作(数据库、HTTP、飞书等);遵守连接策略与写操作确认,失败不自动重试
内置提示与使用说明资源

MCP Server 同时暴露两个只读资源 apemind://usage-guide(中文)与 apemind://usage-guide/en(英文)以及提示模板 search_assistant,客户端可在初始化后读取它们作为系统提示补充,无需在代码里硬编码检索策略。

下一步