Hyper-Extract MCP 只读访问模型
定义
Hyper-Extract MCP 只读访问模型 是指 Hyper-Extract 通过 MCP Server - Hyper-Extract 摘要|MCP Server，把已有 Knowledge Abstract 的查询与导出能力暴露给支持 MCP 的外部助手使用，但访问边界被严格限定为 read + export only。
它可以读取、查询、问答、查看信息和导出结果，但 不会 创建 KA、修改 KA，也不会删除 KA。
这个模型强调的不是把完整的 Hyper-Extract CLI 工作流 搬到协议层，而是把已经由 CLI 生成和维护好的知识资产，安全地交给 MCP 客户端消费。换句话说，创建与增强仍主要发生在 CLI 侧，MCP 侧负责受限访问。
在 Hyper-Extract 文档中的语境
在 Hyper-Extract 的说明里，MCP Server 被定位为一个面向“MCP 能力客户端”的服务接口，典型对象包括 Claude Desktop、IDE agents 等外部助手。
文档对它的描述非常直接：这些助手可以通过 Model Context Protocol 来 query and export your Knowledge Abstracts。这里的重点不是任意操作本地知识库，而是围绕“你已经拥有的 KA”执行查询和导出。
因此，这一模型与 Hyper-Extract CLI 工作流 的关系是：
- CLI 负责生成和维护知识资产，例如先用
he parse产出 KA。 - MCP Server 负责把这些现成资产以统一协议暴露给外部助手。
- 协议访问不延伸到创建、变更、删除生命周期。
核心边界：只允许 read + export
这一模型最重要的边界是权限范围。文档明确写明：MCP Server 是 read + export only。
这意味着允许的操作类型包括：
- 查看已有 KA 的基础信息。
- 基于已有 KA 做检索。
- 基于已有 KA 做问答。
- 把已有 KA 导出到外部可消费的格式或目录。
而明确 不允许 的操作包括：
- create：不能通过 MCP 创建新的 Knowledge Abstract。
- mutate：不能通过 MCP 修改现有 KA 内容、结构或内部状态。
- delete：不能通过 MCP 删除 KA。
这个边界非常关键，因为它说明 MCP Server 不是 CLI 的完全远程代理，更不是可写知识管理接口，而是一个受限的只读/导出访问面。
服务对象：MCP-capable assistants
该模型面向的不是普通终端用户，而是支持 MCP 协议的助手程序。文档给出的例子包括：
- Claude Desktop
- IDE agents
- 其他 MCP-capable assistants
其典型接入方式是让 MCP 客户端把 he-mcp 作为一个 MCP server command 来启动。例如类 Claude Desktop 的配置可将 hyper-extract 这个 server 指向 he-mcp。
这说明 he-mcp 并不是独立知识处理器，而是外部助手访问 Hyper-Extract 资产的协议桥接入口。
所有操作都围绕已有 KA 展开
ka_path 是入口参数
文档明确说明：All tools take a ka_path。也就是说，MCP 暴露出的所有工具，都不是对某个抽象全局知识空间直接操作，而是要求调用方明确指向一个具体 KA 目录。
这个目录必须是由 he parse 创建出来的目录。也就是说：
- MCP 工具处理的是已经存在的 KA。
- 工具不会替你执行
he parse。 - 调用方必须知道目标 KA 的路径，并通过
ka_path传入。
这构成了该访问模型的第二层边界：不仅不能写，而且连“处理对象”都必须是 CLI 预先产出的结果。
不是面向原始文档，而是面向抽取结果
因为 ka_path 指向的是 he parse 生成的目录，所以 MCP Server 面向的是“抽取后的知识资产”，而不是原始 PDF、Markdown 或其他输入文档。
这和 Knowledge Abstract 在 Hyper-Extract 中的定位一致：KA 是后续查看、检索、问答、导出的中心对象。MCP 访问模型实际上是把这套“围绕 KA 的消费能力”开放给外部助手。
关键机制：查询、问答与导出都建立在现有状态上
info：读取 KA 状态
示例中给出：
info(ka_path="./tesla_kb") → {nodes: 48, edges: 70, index_built: true, ...}
这说明只读访问至少包括读取 KA 的结构信息和状态信息，例如节点数、边数、索引是否已建立等。
从这个例子也能看出，MCP 返回的不是对 KA 的修改结果，而是对当前状态的观察。
search 与 ask：依赖已构建索引
文档特别强调，search 和 ask 不是无条件可用。它们要求对应 KA 已经建立索引，索引需要先通过 he build-index 构建。
这意味着：
- 如果只有
he parse生成的 KA，但尚未建立索引，那么不能默认执行search/ask。 - 要让 MCP 客户端可做语义检索与问答，必须先在 CLI 侧对该 KA 执行
he build-index。 - 索引构建仍属于 CLI 工作流的一部分，而不是 MCP 自动代做。
这一点与 CLI Guide - Hyper-Extract 摘要 和 Hyper-Extract CLI 工作流 中的规则一致：检索与问答建立在已建索引之上。
示例中给出的调用也体现了这种能力边界：
search(ka_path="./tesla_kb", query="War of Currents") → {nodes: [...], edges: [...]}ask(ka_path="./tesla_kb", question="Who were Tesla's rivals?") → "Thomas Edison ..."
但这些示例成立的前提，是 ./tesla_kb 已经处于 index_built: true 的状态。
export_obsidian：属于导出能力，但受 feature 开关约束
文档将 export_obsidian 明确归入导出能力的一部分，但它并不是始终可用。它要求对应的 Obsidian 导出 feature 已启用。
如果该能力不可用，系统的行为也不是直接崩溃或无说明失败，而是：
- 返回一条解释性消息。
- 告知该工具当前不可用的原因。
这说明 MCP 只读访问模型中的“导出”也是有条件边界的：并非只要是导出请求就必然能执行，还取决于本地安装或 feature 支持情况。
示例中导出调用为：
export_obsidian(ka_path="./tesla_kb", output="./vault") → "Exported 49 notes to ./vault"
这里可以看出它操作的仍是已有 KA，输出则写到指定目录；但这种导出能力受可选 feature 是否存在的约束。
配置复用：不单独维护第二套模型配置
MCP Server 的模型配置来源不是独立设计的一套新配置，而是直接复用 CLI 的配置文件：~/.he/config.toml。文档明确说明，Server 会读取与你在 CLI 中使用的相同 LLM/embedder 配置，因此需要先运行 he config init ...。
这意味着：
- MCP 访问模型与 CLI 共用同一份 LLM 配置来源。
- MCP 访问模型与 CLI 共用同一份 embedding 配置来源。
- 不需要为了 MCP 额外维护另一套 provider、模型名、endpoint 或 embedder 参数。
这种设计的实际含义是，Hyper-Extract Provider System 的配置入口仍然以 CLI 体系为中心，而 MCP Server 只是复用既有设置。
因此，MCP 侧的可用性部分取决于 CLI 环境是否已正确初始化，例如是否已完成 he config init ... 并写入 ~/.he/config.toml。
安装与运行在该模型中的含义
文档给出的安装与启动方式是：
pip install 'hyperextract[mcp]'
# start the server (stdio transport)
he-mcp
# equivalent:
python -m hyperextract.mcp_server
这里有几个与访问模型相关的要点：
- 需要安装带
[mcp]的额外依赖。 - 启动入口可以是
he-mcp。 python -m hyperextract.mcp_server与he-mcp等价。- 使用的是 stdio transport。
虽然这些是运行细节，但它们进一步表明：he-mcp 是把只读/导出能力暴露给外部助手的服务入口，而不是新的知识抽取命令。
细节与边界
边界 1：MCP 不负责创建 KA
即使一个外部助手可以连接到 MCP Server，它也不能绕过 CLI 直接生成新的 KA。KA 的创建仍由 he parse 完成，MCP 工具只能接入这些既有结果。
边界 2：MCP 不负责增量增强或清理
既然文档明确限制为 read + export only，那么像补充内容、改变结构、清理或删除之类会改变 KA 状态的动作，都不在这个模型内。换言之，MCP 不是 Hyper-Extract CLI 工作流 中 Enhance 或清理类步骤的协议替身。
边界 3：检索/问答依赖前置准备
search 与 ask 的可用性取决于索引是否已经建立。未建索引时，这两个能力不能被视为“默认服务能力”。这与只读模型并不矛盾，因为索引构建是一个前置准备动作，仍应先由 CLI 完成。
边界 4：导出能力也有可选性
export_obsidian 虽属于导出范畴，但其存在与否受 feature 影响。这说明“导出”不是一个无条件统一超集，而是具体导出器按安装特性分别生效。
边界 5：配置来源单一
MCP Server 不自行定义另一套模型配置，避免了 CLI 与协议端配置漂移的问题；但反过来说，如果 CLI 配置未初始化或配置不正确，MCP 端也无法独立补救。
与相关概念的关系
与 Hyper-Extract CLI 工作流 的关系
Hyper-Extract MCP 只读访问模型 可以看作 CLI 工作流的“消费端延伸”。CLI 负责产出和维护 KA，MCP 负责把这些成果提供给外部助手进行读取、检索、问答与导出。
与 Knowledge Abstract 的关系
Knowledge Abstract 是该模型中的核心操作对象。没有既有 KA，就没有 ka_path 可指向，也就没有 MCP 查询与导出的基础。
与 MCP Server - Hyper-Extract 摘要 的关系
后者更偏向源文档摘要与安装运行说明；本条则抽象出其中的访问边界、依赖条件与协议定位。
与 Hyper-Extract MCP 工具依赖约束 的关系
如果说本条解释的是“能做什么、不能做什么”的总体访问模型，那么 Hyper-Extract MCP 工具依赖约束 更适合展开各工具的可用条件、特性依赖与失败反馈方式。
与 he-mcp 的关系
he-mcp 是该只读访问模型的实际启动入口之一，是 MCP 客户端接入 Hyper-Extract 的命令级桥接点。