W
AI-Wiki
CONCEPT

Hyper-Extract MCP 工具依赖约束

定义

Hyper-Extract MCP 工具依赖约束 是指 MCP Server - Hyper-Extract 摘要 中各个 MCP 工具在可成功调用之前，必须满足的一组前置条件与能力边界。这些约束不只是“参数要填完整”，而是明确规定了：

  • MCP 服务端要先被正确启动；
  • 服务端会读取本地配置文件，因此首次使用前要先完成配置初始化；
  • 多数面向具体 Knowledge Abstract 的工具都必须接收 ka_path；
  • ka_path 不能是任意目录，而必须是由 he parse 创建出来的 KA 目录；
  • search 与 ask 不是只要有 KA 就能用，它们还要求该 KA 已经建立索引；
  • export_obsidian 不是无条件可用，它还受 Obsidian 导出功能是否存在的约束。

这些约束共同决定了 MCP 客户端何时可以成功执行查询、问答或导出，也决定了某些能力不可用时系统是返回解释性结果，还是根本无法完成调用。

在本文档中的语境

在 Hyper-Extract 的整体体系里，MCP Server 的定位不是创建或修改知识，而是把已有的 Knowledge Abstract 以 Model Context Protocol 暴露给外部智能体。原文明确说明该服务是 read + export only：它“只读加导出”，不会创建、修改或删除 KA。

因此，这里的依赖约束本质上是对“只读访问路径”的约束，而不是对抽取流程本身的约束。它和 Hyper-Extract CLI 工作流 的关系是：CLI 先负责把文档处理成 KA、建立索引、准备配置；MCP Server 再在这些既有产物之上提供查询、问答和导出能力。

换言之，MCP 工具不是独立于 CLI 资产运行的。它依赖 CLI 事先产出的目录结构、索引和配置，尤其依赖 he parse 与 he build-index 这两个前置步骤。

服务级前置条件

安装与启动方式

要让 MCP 客户端连接到 Hyper-Extract，首先需要安装带 MCP 扩展的包：

  • pip install 'hyperextract[mcp]'

服务端的命令行启动方式有两种，且原文明确说明二者等价：

  • he-mcp
  • python -m hyperextract.mcp_server

这里的“等价”很重要，表示 MCP 客户端在以命令方式连接服务时，可以把其中任一启动方式作为后端命令。文档给出的接入示例就是让 MCP 客户端指向 he-mcp 命令。

配置文件依赖

服务端启动后会读取 ~/.he/config.toml。这不是 MCP 专用配置，而是和 CLI 共用的同一份配置文件。原文因此特别强调，首次使用前要先执行：

  • he config init ...

这条约束意味着：即使 MCP Server 本身能启动，如果 ~/.he/config.toml 没有准备好，服务实际所依赖的 LLM 或 embedding 配置也不会处于预期状态。由于原文写的是“run he config init ... first”，因此它属于首次使用前的明确前置条件，而不是可选优化。

这也把 Hyper-Extract MCP 工具依赖约束 与 Hyper-Extract Provider System 联系起来：MCP 服务端虽然通过 MCP 对外提供工具，但底层模型与嵌入配置仍然沿用 Hyper-Extract 的统一 provider 配置机制。

工具级统一约束：ka_path

原文明确写出：All tools take a ka_path。这表示在 MCP 工具设计中，ka_path 是统一的重要输入约束。

但这个“统一”要结合示例理解：从实际使用场景看，ka_path 是面向具体 KA 操作的工具共同依赖的核心参数，例如：

  • info(ka_path="./tesla_kb")
  • search(ka_path="./tesla_kb", query="War of Currents")
  • ask(ka_path="./tesla_kb", question="Who were Tesla's rivals?")
  • export_obsidian(ka_path="./tesla_kb", output="./vault")

同时，文档又给出 list_templates() 这样的示例，它不展示 ka_path。因此在写作上更准确的理解是：MCP Server 的工具体系整体围绕 KA 工作，而具体面向某个 KA 的核心工具统一要求 ka_path。无论如何，本文必须保留原文的硬性事实：ka_path 是 MCP 工具约束中的统一关键参数。

更关键的是，ka_path 不能随意填写。原文限定它必须是 a directory created by he parse。也就是说：

  • ka_path 必须指向一个目录，而不是单个文件；
  • 该目录必须是执行 he parse 后生成的 KA 目录；
  • 任何普通目录、手工拼出来的目录、不是由 he parse 创建的目录，都不满足这一约束。

这条规则把 MCP 工具与 Knowledge Abstract 的实体边界绑定起来：MCP 操作对象不是任意文本集合，而是 Hyper-Extract 标准流程创建出来的 KA。

索引依赖：search 与 ask 的额外前置条件

search 和 ask 并不是有 ka_path 就能运行。原文明确写出：

  • search / ask require an index
  • 索引需要通过 he build-index 构建

这意味着这两个工具比 info 之类的工具多出一层前置条件：

  1. 先有由 he parse 创建的 KA 目录；
  2. 再对该 KA 执行 he build-index；
  3. 之后 MCP 中的 search 与 ask 才具备可用前提。

这是一个很明确的能力分层：

  • info 主要读取 KA 的已有结构信息；
  • search 依赖检索索引；
  • ask 也依赖检索索引，因为它要在已索引的知识上进行问答。

文档中的 info 示例还返回了 index_built: true，这间接说明索引状态本身就是一个可观察条件。示例为：

  • info(ka_path="./tesla_kb") → {nodes: 48, edges: 70, index_built: true, ...}

这里至少包含三个具体事实：

  • 该 KA 示例有 48 个 nodes；
  • 有 70 个 edges；
  • 索引已建立，即 index_built: true。

而正因为 search 与 ask 依赖索引，所以 index_built 这种状态对 MCP 调用是否成立具有直接判断意义。

功能开关依赖：export_obsidian 的可用性边界

export_obsidian 的约束与 search、ask 又不同。它不是索引依赖，而是受 Obsidian 导出功能是否可用所限制。原文明确说明：

  • export_obsidian requires the Obsidian export feature

这表示即便 ka_path 合法、MCP Server 已正常启动、配置文件也存在，export_obsidian 仍然可能因为缺少该导出能力而不可用。

更重要的是，不可用时的返回方式也被原文定义得很清楚：

  • 如果该功能不可用，工具会返回 解释性消息；
  • 它不是以“报错失败”的方式结束调用。

这是一条很有辨识度的边界规则。它说明 export_obsidian 的失败语义被设计为“能力说明型返回”，而不是“工具崩溃型失败”。对 MCP 客户端来说，这意味着：

  • 不能简单把没有导出成功等同于系统异常；
  • 要考虑工具可能正常返回一段说明，告知该功能当前不可用。

在可用场景下，文档示例给出的返回是：

  • export_obsidian(ka_path="./tesla_kb", output="./vault") → "Exported 49 notes to ./vault"

这个示例也保留了一个具体数字事实：示例中共导出了 49 条 notes 到 ./vault。

不同工具的依赖条件并不相同

本文最容易被误解的地方，是把所有 MCP 工具当成完全同构的接口。原文实际上给出的正是“同属一个服务，但依赖条件分层不同”的结构。

list_templates

list_templates() 的作用是列出模板。示例返回形式为：

  • [{name: "general/biography_graph", ...}, ...]

它说明该工具至少可以返回模板名称，如 general/biography_graph。从示例看，它不像 info、search、ask、export_obsidian 那样围绕某个已有 KA 目录展开，因此它和后几者的依赖形态并不完全相同。

info

info 依赖一个有效的 ka_path，但原文没有要求它必须先建立索引才能调用。它主要用于读取 KA 状态，例如 nodes、edges 以及 index_built 标记。

因此，info 的前置条件至少包括：

  • MCP Server 已启动；
  • ~/.he/config.toml 已按要求准备；
  • ka_path 指向 he parse 创建的 KA 目录。

但它不具备 search、ask 那种“必须先建索引”的硬性额外要求。

search 的前置条件比 info 更严格：

  • 需要有效 ka_path；
  • 该路径必须来自 he parse 创建的 KA；
  • 必须已经执行 he build-index。

示例查询词是 War of Currents，返回结构是：

  • {nodes: [...], edges: [...]}

这表明它返回的不是单纯一段文本，而是与 KA 图谱内容相关的节点和边结果集。

ask

ask 与 search 一样依赖索引。示例问题是：

  • Who were Tesla's rivals?

示例回答是：

  • Thomas Edison ...

这说明 ask 面向自然语言问答输出，返回结果形式与 search 不同，但其可用前提与 search 一样都包含“必须先建索引”。

export_obsidian

export_obsidian 既需要针对某个 KA 的 ka_path，又额外要求 Obsidian export feature 可用。它和 search / ask 的区别在于，原文没有把“已建立索引”写成它的必要条件；它受约束的重点在于导出能力开关，而不是检索索引。

因此，这五个例子共同说明：MCP 工具虽然属于同一服务，但并非共享一套完全相同的依赖矩阵。

关键机制：CLI 产物复用而非 MCP 内部生成

这些依赖约束背后的核心机制是：MCP Server 并不自己创建知识资产，而是复用 CLI 已经准备好的产物。

对应关系可以概括为：

  • he parse 负责创建 KA 目录；
  • he build-index 负责为 KA 建立索引；
  • he config init ... 负责初始化服务和 CLI 共用的配置文件；
  • he-mcp 或 python -m hyperextract.mcp_server 负责把这些现有资产以 MCP 形式暴露给客户端。

因此，Hyper-Extract MCP 工具依赖约束 实际上是 Hyper-Extract CLI 工作流 在 MCP 访问层的投影：MCP 并没有绕过 CLI 规则，而是直接建立在其结果之上。

细节与边界

1. ka_path 是来源约束，不只是路径格式约束

这里限制的不是“路径长什么样”，而是“路径从哪里来”。即使某个目录名称看起来像 KA，只要不是 he parse 创建出来的，就不满足原文约束。

2. 索引要求只对部分工具成立

原文只明确把索引要求加在 search 与 ask 上，而没有泛化到所有工具。因此不能把“所有 MCP 工具都必须先 he build-index”当成通用规则。

3. 配置初始化属于首次使用前置条件

因为服务会读取 ~/.he/config.toml，所以 he config init ... 不是与 MCP 无关的 CLI 准备动作，而是 MCP 服务成功运行的环境条件之一。

4. 启动方式是命令式接入

MCP 客户端是通过命令连接该服务的，文档给出的示例就是把客户端配置中的 command 指向 he-mcp。这说明常见接入模型是本地命令拉起 stdio transport 的服务进程。

5. export_obsidian 的不可用不等于异常崩溃

这是最需要保留的异常语义边界：当导出功能不可用时，预期行为是返回解释性消息，而不是直接以失败报错结束。这与很多“工具缺功能就抛错”的系统设计不同。

与相关条目的关系

  • MCP Server - Hyper-Extract 摘要：本页讨论的所有约束都来自该服务的安装、连接与工具说明。
  • Hyper-Extract MCP 只读访问模型：本页的依赖条件服务于只读与导出访问，不涉及创建、修改、删除 KA。
  • he-mcp：它是 MCP Server 的直接启动命令，也是 MCP 客户端最常见的命令式连接目标。
  • Hyper-Extract CLI 工作流：MCP 工具依赖的 ka_path、索引和配置，本质上都来自 CLI 工作流的前序步骤。
  • Knowledge Abstract：ka_path 所指向的正是由 he parse 创建的 KA 目录，MCP 工具围绕它执行读取、检索、问答和导出。