W
AI-Wiki
SOURCE

MCP Server - Hyper-Extract 摘要

文档概览

Hyper-Extract 内置了一个 MCP Server，用于让支持 Model Context Protocol 的助手访问用户已经生成好的 Knowledge Abstract。文档点名的典型客户端包括 Claude Desktop 和 IDE agents 等 MCP-capable assistants。

这套能力的边界被写得非常明确：服务器提供的是 read + export only。也就是说，它只允许查询和导出已有 KA，不会创建、修改、变异或删除任何 Knowledge Abstract。这意味着它不是一个通用写入接口，而是围绕只读探索与结果导出的受限访问层。

从工作流位置上看，这个 MCP Server 建立在 Hyper-Extract CLI 工作流 之后：先通过 he parse 生成 KA，必要时再通过 he build-index 建立检索索引，随后助手才能通过 MCP 工具对该 KA 做信息查看、搜索、问答和导出。

关键事实

内置服务器与适用对象

  • Hyper-Extract 自带 MCP Server，不需要用户自己额外实现服务端。
  • 它面向支持 Model Context Protocol 的助手。
  • 文档中明确举例：Claude Desktop、IDE agents 等。

能力边界：只读 + 导出

  • 服务器能力被限定为 read + export only。
  • 它可以查询和导出已有的 Knowledge Abstract。
  • 它不会创建 KA。
  • 它不会修改 KA。
  • 它不会删除 KA。
  • 原文还用了 never creates, mutates, or deletes a KA 这样的强表述，说明这是产品级约束，不是建议做法。

安装命令

安装方式在文档中直接给出：

pip install 'hyperextract[mcp]'

这里说明 MCP 支持是通过 hyperextract[mcp] 这个额外安装项启用的，而不是基础安装说明中的隐含默认能力。

启动方式与传输方式

文档给出两种等价启动方式：

he-mcp

以及：

python -m hyperextract.mcp_server
  • 两者是等价命令。
  • 运行时使用的是 stdio transport。
  • 因此，客户端连接方式不是去填一个 HTTP 地址，而是把 MCP 客户端的命令入口指向 he-mcp 这个本地命令。

配置文件来源

MCP Server 会读取：

  • ~/.he/config.toml

这个配置文件与 CLI 共用，因此文档特别提醒：通常要先执行 he config init ...，把 LLM 和 embedder 配置好，MCP Server 才能使用同样的模型与嵌入配置工作。

这点与 Hyper-Extract Provider System 和 CLI 配置机制是连通的：MCP Server 并不维护一套独立配置，而是复用命令行环境。

MCP 客户端连接方式

连接方法非常直接：把 MCP 客户端的 command 指向 he-mcp。

文档给出 Claude Desktop 风格配置示例：

{
  "mcpServers": {
    "hyper-extract": {
      "command": "he-mcp"
    }
  }
}

可见这里的关键点不是网络端口，而是本地命令调用。对任何支持 MCP 的客户端来说，只要支持以命令方式启动 server，就可以按这个模式接入。

ka_path 的强依赖

文档明确说：所有工具都需要 ka_path。

而且这个 ka_path 不是任意目录，它必须是：

  • 由 he parse 创建出来的目录。

这说明 MCP 工具不是直接面向原始文档运行，也不是面向随意拼装的目录结构运行，而是面向已经生成好的 KA 目录。这个要求和 Knowledge Abstract 在整个 CLI 工作流中的中心地位一致。

search 与 ask 的索引依赖

  • search 依赖索引。
  • ask 也依赖索引。
  • 在调用这两类工具之前，必须先运行 he build-index。

也就是说，仅仅执行 he parse 生成 KA 还不够；如果用户希望通过 MCP 做语义检索或问答，需要继续走到索引构建这一步。这与 CLI Guide - Hyper-Extract 摘要 中对 he build-index 作用的描述一致。

重要细节

配置与前置步骤的实际含义

文档虽然只用一句话提到 ~/.he/config.toml 和 he config init ...，但信息量很关键：

  1. MCP Server 不是独立配置模型。
  2. 它直接复用 CLI 的 LLM/embedder 配置。
  3. 因此如果用户还没初始化 CLI 配置，MCP Server 通常也无法正常完成依赖模型或嵌入器的操作。
  4. 这尤其影响到依赖检索或问答的工具，因为相关能力通常需要 embeddings 或 LLM 配置配合。

从运维角度看，这减少了重复配置，但也意味着排查问题时要优先检查 CLI 配置是否已初始化。

export_obsidian 的例外行为

文档专门补充了一个边界条件：export_obsidian 需要 Obsidian 导出功能本身可用，也就是需要具备 he export obsidian 对应的导出能力。

如果该能力不可用，工具的行为不是直接异常失败，而是：

  • 返回一条解释性消息。
  • 明确说明为什么不可用。
  • 不是无提示报错。

这表示该工具在能力探测失败时采用的是较温和的降级反馈方式，方便 MCP 客户端或助手向用户解释原因。

示例会话透露出的工具形态

文档最后给出了一段示例会话，能帮助理解 MCP 工具的输入输出风格：

list_templates() → [{name: "general/biography_graph", ...}, ...]
info(ka_path="./tesla_kb") → {nodes: 48, edges: 70, index_built: true, ...}
search(ka_path="./tesla_kb",
 query="War of Currents") → {nodes: [...], edges: [...]}
ask(ka_path="./tesla_kb",
 question="Who were Tesla's rivals?") → "Thomas Edison ..."
export_obsidian(ka_path="./tesla_kb",
 output="./vault") → "Exported 49 notes to ./vault"

从这组例子可以确认几件事：

  • 工具并不只是返回纯文本，也可能返回结构化对象。
  • info 会返回图谱规模与索引状态，例如示例中有 nodes: 48、edges: 70、index_built: true。
  • search 的输入是 query，返回结果里包含节点和边，说明其结果贴近图谱/知识结构。
  • ask 的输入是自然语言问题，输出是答案文本。
  • export_obsidian 需要额外提供 output 路径，示例结果为 Exported 49 notes to ./vault，说明导出会生成具体数量的笔记文件。

需要注意的是，这些示例主要用于说明接口行为，不应被理解为固定输出格式或固定数据规模；但其中的字段名、参数名和依赖关系具有很高参考价值。

与 CLI 工作流的关系

该来源页虽然主题是 MCP Server，但它隐含了一条很清楚的使用顺序：

  1. 先配置 CLI：he config init ...。
  2. 用 he parse 生成 Knowledge Abstract，得到可供工具使用的 ka_path 目录。
  3. 如果要使用 search 或 ask，先运行 he build-index。
  4. 然后由 Claude Desktop、IDE agent 等 MCP 客户端通过 he-mcp 接入。
  5. 最后执行只读查询或导出操作，而不是内容写入操作。

这使得 MCP Server 更像是 Hyper-Extract CLI 工作流 的访问层，而不是替代 CLI 的主入口。

约束、边界与例外

  • 只支持 read + export，不支持 create / mutate / delete。
  • 所有工具都要求 ka_path。
  • ka_path 必须是 he parse 创建的 KA 目录，不是任意目录。
  • search 和 ask 不能在无索引状态下直接工作，必须先 he build-index。
  • export_obsidian 依赖相应导出功能存在；缺失时返回解释性消息，而非硬失败。
  • 服务通过 stdio 运行，因此接入重点是命令配置，不是开放网络服务地址。

相关条目