W
AI-Wiki
ENTITY

he-mcp

定义

he-mcp 是 Hyper-Extract 的 MCP Server 主启动命令，也是 MCP 客户端接入 Hyper-Extract 知识查询与导出能力时最直接的命令入口。

它启动的是一个基于 MCP 的服务端进程，供 Claude Desktop、IDE agent 等支持 MCP 的助手连接，用来查询和导出你的 Knowledge Abstract。

该命令的等价启动方式是：python -m hyperextract.mcp_server。

角色与职责

he-mcp 的职责不是执行 Hyper-Extract CLI 工作流 中的抽取、增量补充或索引构建，而是把已经存在的知识资产以 MCP 服务形式暴露给外部客户端。

它主要承担两类能力：

文档明确说明该 MCP Server 是 只读 + 导出 模式：它不会创建、修改或删除任何 KA。

这意味着 he-mcp 适合接入问答、搜索、浏览、导出类助手流程，但不负责生成 KA，也不负责写回知识内容。

安装与启动

使用 he-mcp 前，安装前提是：

pip install 'hyperextract[mcp]'

安装完成后，可直接启动服务器：

he-mcp

等价写法为：

python -m hyperextract.mcp_server

这里的 he-mcp 不是普通的一次性 CLI 子命令，而是 MCP Server 的启动入口。

传输方式

he-mcp 通过 stdio transport 运行。

这表示 MCP 客户端不是通过单独声明 HTTP 地址来连接它，而是通过启动本地命令进程并经标准输入、标准输出与该服务通信。

因此，在 Claude Desktop 风格的 MCP 配置中，通常只需要把命令指向 he-mcp，而不是填写额外的网络监听地址。

配置来源

he-mcp 会读取 ~/.he/config.toml。

这份配置文件与 Hyper-Extract CLI 共用，也就是说，MCP Server 复用了命令行工具的 LLM 和 embedder 配置，而不是维护一套独立配置。

原文特别提示：因为它使用与 CLI 相同的配置，所以应先完成类似 he config init ... 的初始化，再启动该服务。

这说明 he-mcp 的模型访问能力依赖既有 CLI 环境；如果 CLI 侧配置未建立或不完整，MCP Server 侧也无法正确继承这些设置。

在 MCP 客户端中的接入方式

MCP 客户端需要把服务命令指向 he-mcp。

Claude Desktop 风格配置示例如下：

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

这里的关键事实是：客户端通过 command: he-mcp 连接该服务。

由于服务采用 stdio transport，上述配置的重点是启动本地命令，而不是配置远程连接参数。

使用边界与依赖条件

he-mcp 暴露的工具都需要传入 ka_path，该路径指向一个由 he parse 创建出来的目录。

这意味着它处理的是已经存在的 KA 目录，而不是原始文档文件；如果没有先经过 he parse 生成 KA，MCP 工具就没有可操作对象。

其中，search 和 ask 还要求对应 KA 已经建立索引；索引需要先通过 he build-index 构建。

因此，虽然 he-mcp 能提供搜索与问答能力，但前提不是“只要有 KA 即可”，而是：

  • 有效的 ka_path 必须存在；
  • KA 必须是由 he parse 生成的目录；
  • 如果要使用 search 或 ask，还必须先执行 he build-index。

另外，export_obsidian 依赖 Obsidian 导出功能。

如果该导出特性不可用，工具不会直接失败崩溃，而是返回一条解释性消息，说明该能力当前不可用。

这体现出 he-mcp 的一个边界：它可以作为导出入口，但实际可导出的格式仍受 Hyper-Extract 本体功能与安装特性的约束。

典型能力示例

文档给出的 MCP 会话示例表明，he-mcp 启动后可承载如下操作：

  • list_templates()：列出模板，例如返回包含 general/biography_graph 在内的模板列表；
  • info(ka_path="./tesla_kb")：返回 KA 信息，例如 nodes: 48、edges: 70、index_built: true；
  • search(ka_path="./tesla_kb", query="War of Currents")：返回相关节点与边；
  • 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。

这些例子进一步说明：he-mcp 连接的不是抽取流程本身，而是面向已生成知识库的读、查、问、导出接口。

与相关条目的关系