OpenZIM MCP Server

OpenZIM MCP Server

Transform static ZIM archives into dynamic knowledge engines for AI models

______________________________________________________________________

🆕 v1.1.0中的新功能：结构化工具输出！ 所有17个JSON返回工具现在都发出MCP structuredContent 除了传统的文本信封，不再有双字符串JSON，也不再有转义汤。此外，还修复了新方案存档的主要命名空间处理问题(list_namespaces / browse_namespace / walk_namespace 在维基百科风格的ZIM上被默默打破），分页 extract_article_links不区分大小写 find_entry_by_title 通过适当的评分和浏览器MCP客户端的CORS支持。 了解更多→ 还在v1.0.0的亮点上吗？流式HTTP传输、批条目检索和每条条目资源都记录在 v1.0.0节.

双模式支持： 在简单模式（1个智能自然语言工具，默认）或高级模式（21个专用工具，加上3个MCP提示和3个MCP资源）之间进行选择，以匹配您的LLM能力。

专为LLM Intelligence打造

OpenZIM MCP将静态ZIM档案转换为大型语言模型的动态知识引擎。 与基本文件读取器不同，此工具提供 *智能、结构化访问* LLM需要有效地导航和理解庞大的知识库。

为什么LLMs喜欢OpenZIM MCP：

• 智能导航：按命名空间（文章、元数据、媒体）浏览，而不是盲目搜索
• 上下文感知发现：获取文章结构、关系和元数据，以便更深入地理解
• 智能搜索：高级过滤、自动完成建议和相关性排名结果
• 性能优化：缓存操作和分页可防止大量存档超时
• 关系映射：提取内部/外部链接以了解内容连接

无论您是在构建研究助理、知识聊天机器人还是内容分析系统，OpenZIM MCP都能为您的LLM提供所需的结构化访问模式，以释放离线知识档案的全部潜力。不再在原始文本转储中摸索！

OpenZIM MCP 是一个现代、安全、高性能的MCP（模型上下文协议）服务器，使AI模型能够访问和搜索 [ZIM格式]() 离线知识库。

[以星]() （Zeno IMproved）是由 openZIM项目，专为离线存储和访问网站内容而设计。该格式支持使用Z标准压缩的高压缩率（自2021年以来默认），并支持快速全文搜索，使其成为将整个维基百科内容和其他大型参考资料存储在相对紧凑的文件中的理想选择。openZIM项目由维基媒体CH赞助，并得到维基媒体基金会的支持，确保该格式在离线知识访问中的持续发展和采用，特别是在没有可靠互联网连接的环境中。

特性

• 双模式支持：在简单模式（1个智能自然语言工具，默认）或高级模式（21个专用工具）之间进行选择
• 可流式HTTP传输: 🆕 通过HTTP作为长时间运行的服务运行——承载令牌认证、CORS、健康端点、多拱形Docker映像和资源订阅
• 批量条目检索: 🆕 每次通话最多可提取50个条目 get_zim_entries --与HTTP自然配对，往返成本很重要
• 按条目MCP资源: 🆕 通过流式传输单个条目 zim://{name}/entry/{path} 使用本机MIME类型--直接浏览HTML、PDF和图像
• 资源订阅: 🆕 客户订阅 zim://files 和 zim://{name} 并接收 notifications/resources/updated 当档案发生变化时
• 多档案搜索：使用以下命令一次搜索每个ZIM文件 search_all --无需知道哪个档案保存了答案
• MCP提示：预构建的工作流斜线命令(/research, /summarize, /explore)协调多步骤ZIM操作
• 按标题查找条目：使用以下命令立即将标题解析为条目路径 find_entry_by_title --不区分大小写，可选跨文件
• 二进制内容检索：为多代理工作流提取PDF、图像、视频和其他嵌入式媒体
• 安全第一：全面的输入验证和路径遍历保护
• 高性能：智能缓存和优化的ZIM文件操作
• 智能检索：从直接访问自动回退到基于搜索的检索，以实现可靠的条目访问
• 测试良好：通过全面的测试套件实现80%以上的测试覆盖率
• 现代建筑：模块化设计，带有依赖注入
• 类型安全：整个代码库中的完整类型注释
• 可配置的：具有验证功能的灵活配置
• 可观察对象：结构化日志记录和健康监测

v1.2.0的新增功能

紧凑模式 zim_query （默认为简单模式）

简单模式适用于小型/设备上的LLM，其响应预算因维基百科规模的工具输出而崩溃。典型的 extract_article_links 对“光合作用”类文章的回应约为36 KB；一个包含5个3000字符片段的搜索响应大约为15KB；10个截面的结构响应 preview 块大小约为17KB。这些散文都不是一个小型法学硕士所能做的——它只是需要背景知识。

zim_query 现在接受a compact: bool = True 该参数将五个意图从JSON转换为平面markdown呈现，将搜索片段截断为250个字符，剥离维基百科风格的markdown链接语法([text](href "tooltip") → text)从文章正文中提取，并对最终响应应用6000个字符的硬上限。在典型的维基百科查询路径上，响应会缩小3-6倍，同时保留小型LLM用于驱动后续工具调用的每个导航钩子。

迁移说明

这是对以编程方式解析由返回的遗留JSON形状的调用者的行为更改 query="links in X", query="structure of X", query="find article titled X", query="articles related to X", query="walk namespace X"，或 query="list namespaces"之前的形状仍然可用--通过 compact=False 选择退出：

zim_query("links in Photosynthesis", options={"compact": False})

其他工具改进

• tell_me_about 自动获取强标题匹配的文章，而不是返回低置信度的搜索列表，并返回线索部分+部分TOC，而不是全文。
• 裸主题门现在接受非拉丁字母的主题名称（中文、西里尔文、阿拉伯语、天城文、希伯来语）——以前只使用ASCII的标记器会默默地拒绝它们 量子力学 陷入了低置信度搜索。
• 会话填充/元指令("do both", "try again", "test this tool", "ok")返回一个简短的初学者查询剧本，而不是由停用词冲突主导的20万次点击搜索。
• 0结果搜索显示恢复路径(suggestions for ..., find article titled ...)内联。
• 这四种搜索风格的意图在呈现的输出中共享一个紧凑的分页页脚。
• 幻听 zim_file_path 价值观("wikipedia.zim" 针对某档案馆 /data/wiki_en.zim)通过基名匹配来解决，而不是通过拒绝 "Access denied".

波兰语

• ReDoS保护：markdown链接条和代码段截断正则表达式现在通过意图解析器使用的基于线程的超时包装器运行，因此对抗性未关闭 [text](URL 不会造成灾难性的倒退。
• 紧凑渲染层移动到自己的模块(openzim_mcp.compact_renderers) — simple_tools.py 现在专注于意图调度。

v2.0.0a2的新增功能

v2工作的B阶段。为所有返回列表的工具引入共享响应契约——v1.x的有线格式中断。升级前必须更新客户端。

响应合同（v2）

每个列表返回工具返回相同的五个合约密钥：

加上A阶段 _meta 作为兄弟姐妹的信封。

分页输入

每个分页工具都接受 cursor （首选）或 offset （方便）。如果 两者都被供应， cursor 获胜。

光标格式

游标是URL安全的base64编码JSON {v: 1, t: , s: }. 光标是 工具绑定 --将一个工具的光标传递给另一个工具会引发 明显的错误。光标是 不透明的 --客户不应解读它们。

没有自然分页的工具

工具如 find_entry_by_title, get_search_suggestions，以及 list_zim_files 在一次通话中返回所有匹配项。他们仍然发出合同： done=true, next_cursor=null, total=len(results).

extract_article_links 需要 kind

extract_article_links 每次调用返回一个类别(kind=internal 通过 默认）。使用 kind=external 或 kind=media 对于其他类别。 按类别统计表面 category_totals: {internal, external, media}.

线格式断点注释

v2.0.0a2是v1.x的有线格式中断——请参阅CHANGELOG了解每个工具键的重命名。

v2.0.0a1的新增功能

首次v2预发布。多阶段v2工作的A阶段。所有变化都在工具特征层叠加；小型紧凑模式散文变为空搜索结果。

响应元数据(_meta 信封）

现在，每个字典返回工具都包含一个 _meta 按键：

{
  "tokens_est": 4283,
  "chars": 17034,
  "truncated": true,
  "more_at_offset": 17000,
  "total_chars": 87421,
  "suggestions": [
    {"type": "alt_spelling", "value": "Photosynthesis"}
  ],
  "reason": "0_hits"
}

tokens_est 是一个 tiktoken cl100k_base 估计加上5%的垫。将其用于情境预算；在普通标记器中，它的准确度为±10%。 suggestions 和 reason 仅在空/低置信度结果上存在。

紧凑型散文页脚

简单模式响应以单行markdown blockquote结尾：

> ~4.2K tokens · 17K of 87K chars · pass `offset=17000` for more

空结果使建议内联：

> No results. Try: `suggestions for Photosynthesis` · `search photosynthesis chlorophyll` · or try ZIM `wikipedia_en_all`

集 OPENZIM_MCP_META__FOOTER_ENABLED=false 为了压制。

紧凑型信息框和桌面处理

在 compact=True （简单模式默认值）：

• 维基百科风格 .infobox / .vcard 表格变成了附加在正文前面的Markdown KV列表。最多30排；可通过以下方式配置 OPENZIM_MCP_CONTENT__INFOBOX_KV_LIMIT.
• 文本超过8行或600个字符的表将成为占位符： [Table N: 47 rows × 6 cols — pass compact=False to expand]阈值可通过以下方式配置 OPENZIM_MCP_CONTENT__TABLE_ROW_THRESHOLD 和 OPENZIM_MCP_CONTENT__TABLE_CHAR_THRESHOLD.

compact=False 保持v1.2.0字节的相同行为。

耐拼写错误的标题查找

find_entry_by_title 当直接路径查找和libzim建议索引都没有返回高置信度匹配时，会退回到单编辑变体（转置、单字符删除）。模糊校正命中分数 0.85 （可通过以下方式配置 OPENZIM_MCP_SEARCH__FUZZY_TITLE_SCORE_PENALTY)以确保精确匹配始终排名更高。触发回退的最小查询长度为4个字符(OPENZIM_MCP_SEARCH__FUZZY_TITLE_MIN_QUERY_LEN).

v2阶段A环境变量

v1.1.0的新增功能

结构化工具输出

17个JSON返回工具现在发出MCP structuredContent 伴随着遗产 content[].text 信封。旧客户端继续解析文本JSON；新客户直接阅读字典。最大的受益者是 search_all，谁 per_file[].result 字段曾经是一个预渲染的markdown blob，通过两次转义 json.dumps --现在它是一个真正的嵌套字典。

四种散文/标记工具(search_zim_file, search_with_filters, get_zim_entry, get_main_page)以及简单模式 zim_query 继续停留 -> str 通过设计。

命名空间处理，已修复

在新方案ZIM归档（当前Kiwix维基百科构建使用的现代格式）中，libzim的可迭代表面仅公开C名称空间，并通过以下方式访问元数据 archive.metadata_keys之前的代码解析了每个条目路径的第一个字符 *作为* 命名空间，因此 Evolution 看起来像命名空间 'E', Bob_Dylan 喜欢 'B', favicon.png 喜欢 'F' -包括表情符号桶，如 '🐜'. search_with_filters(namespace='C') 正在悄然下降约95%的合法点击率。

list_namespaces, browse_namespace, walk_namespace，以及 namespace= 过滤器现在开始分支 archive.has_new_namespace_scheme：新方案C使用 entry_count 作为一个权威的总数，M是从 metadata_keysW通过以下方式浮出水面 has_main_entry / has_illustration旧方案档案不受影响。

分页为 extract_article_links

extract_article_links 之前在一次通话中丢弃了所有内部/外部/媒体链接。在一篇链接量很大的维基百科文章（约6k个链接）上，该文章的大小约为400KB，超出了响应令牌的预算。该工具现在接受 limit / offset / kind 参数；满载船只 total_internal_links / total_external_links / total_media_links 这样呼叫者就可以调整下一页的大小。解析后的提取每个条目缓存一次，并在内存中切片（缓存页面的速度提高了约40倍）。

更聪明 find_entry_by_title

快速通道区分大小写，所以 "evolution" 反对一个名为 "Evolution" 错过并通过硬编码的建议回退 score: 0.8现在，快速路径尝试了五个案例变体×C/A名称空间；建议结果在（0,0.95\]中获得排名导出的分数，因此精确的不区分大小写的匹配（提升到1.0）总是高于部分匹配。

每个条目的资源大小上限

zim://{name}/entry/{path} 现在，UTF-8将文本主体的大小限制在256 KB，并附有一条指向 get_zim_entry 用于分页读取。超大的二元体是 *拒绝* （不是静默剪切，因为切片的PDF/PNG不会打开）-调用者应该使用 get_binary_entry，其中明确 max_size_bytes 和一个 truncated 旗帜。

简单模式确实有效

_register_simple_tools 也在打电话 _register_advanced_tools，所以简单模式客户端无论如何都会在提示符中收到每个高级工具的模式——这破坏了模式的全部意义，并将预填充膨胀到数千个令牌范围内。修复：简单模式现在只注册一个工具(zim_query).与llama.cpp的MCP webui相比，单圈提示大小从约6200个令牌降至约1100个。

浏览器MCP客户端的CORS

HTTP传输的CORS层增加了两个功能：

• MCP-Protocol-Version 现在在 allow_headers浏览器MCP客户端根据MCP规范在每次初始化后请求时发送此消息；没有它，第二次飞行前返回 400 Disallowed CORS headers 连接中断。
• DELETE 现在在 allow_methodsMCP流式HTTP SDK使用DELETE进行显式会话终止。

波兰语

• get_server_health 现在报告一个真实的 started_at 和 uptime_seconds 而不是 "unknown".
• 配置编校格式已从误导性更改 ...data 明确无误 /data.
• 服务器工具时间戳通过单个 _utc_now_iso() 助手，因此响应不再将时区感知的UTC与简单的本地混合在一起。
• zim_query("") 使用示例查询预先拒绝空输入，而不是进行无操作搜索。
• get_search_suggestions 模式现在记录了2个字符的最小值。
• “缓存命中率低”警告在评论之前等待≥50次访问（之前在正常会话预热期间以22%的速度触发）。
• get_zim_entry的截断尾部现在读取“of body content”，因此调用者可以告诉限制适用于body，而不是包装器头。

v1.0.0的新增功能

可流式HTTP传输

将OpenZIM MCP作为长时间运行的服务运行。通过 --transport http （或设置 OPENZIM_MCP_TRANSPORT=http)服务器在上启动Starlette应用程序 127.0.0.1:8000 默认情况下为：

• 承载令牌身份验证 --set OPENZIM_MCP_AUTH_TOKEN；比较是时间安全的，尝试的令牌永远不会被记录。
• 安全默认启动检查 --服务器 *拒绝* 绑定没有令牌的非本地主机。（绑定 127.0.0.1 仅限本地访问；在TLS前面放置一个反向代理。)
• CORS允许列表 --明确起源 OPENZIM_MCP_CORS_ORIGINS；通配符 * 启动时被拒绝。
• 健康终点 — /healthz （活性）和 /readyz （至少有一个允许的目录是可读的）。两者都免于身份验证，因此探测器可以干净地工作。
• 多拱形Docker镜像 — ghcr.io/cameronrye/openzim-mcp:1.1.2，为 linux/amd64 和 linux/arm64，以非root身份运行。

传统SSE传输也可通过以下方式获得 --transport sse （或 OPENZIM_MCP_TRANSPORT=sse)对于尚未迁移到流式HTTP的客户端。苏格兰和南方能源公司确实如此 不 应用承载令牌/CORS/健康端点中间件，使服务器 *拒绝* 首先 --transport sse 除了 127.0.0.1/::1/localhost。对于暴露的部署，请使用 --transport http.

批量条目检索

get_zim_entries 在一次通话中最多可提取50个条目。每次输入失败不会中止批处理——每个结果都包括其 index 从输入顺序加上 content （成功）或 error （失败）。不同 zim_file_path 允许在一个批处理中使用值，因此多存档工作流可以从单个搜索中展开。单个归档批可以传递与顶级文件配对的裸路径字符串 zim_file_path 默认情况下，调用站点保持平坦，而不是字典繁重。

按条目MCP资源

zim://{name}/entry/{path} 使用其本机MIME类型公开单个条目：

• HTML和文本条目返回文本正文(text/html, text/plain, application/json, ...).
• 二进制条目（图像、PDF）返回原始字节（FastMCP base64封装它们）。

编码要求： 客户端必须进行URL编码 / 作为 %2F 在 {path} 分段。FastMCP的URI模板引擎处理 / 作为段分隔符，因此文字斜线不会路由。例子： zim://wikipedia_en/entry/C%2FClimate_change（这是电流的限制 mcp[cli] SDK。)

资源订阅

订阅 zim://files 或 zim://{name} 服务器发出 notifications/resources/updated 每当目录内容发生变化或 .zim 文件被替换。轮询间隔是可配置的(OPENZIM_MCP_WATCH_INTERVAL_SECONDS，默认5秒），该功能可以通过以下方式禁用 OPENZIM_MCP_SUBSCRIPTIONS_ENABLED=false.实现说明：这取决于私有的FastMCP属性(_mcp_server)用于处理程序注册。

波兰语和修复

更智能的归档处理

• get_related_articles 解析源条目目录的相对href，并在域方案存档上正确标识内容命名空间（之前未返回任何内容）。
• 建议回退使用 SuggestionSearcher(archive).suggest(text) （之前 archive.suggest() 呼叫不存在）。
• list_zim_files 不区分大小写 name_filter 子字符串参数；一个共享缓存槽，而不管过滤器值如何。
• search_zim_file 接受不透明 cursor 参数；仅传递光标即可恢复分页，而无需重新启动查询。

清洁成分提取

• 标题id解析失败 id → mw头条主播→ 前面的 ` → 蛞蝓，返回 (id, source)` 因此，消费者可以区分真正的锚和合成的蛞蝓。
• 摘要提取跳过USWDS横幅，跳过第一个上方的导航块 `

` （MedlinePlus/NHI/NIST风格的网站）。

• 链接提取删除了不可导航的方案(javascript:, mailto:, tel:, data:, blob:, vbscript:).
• 每个入口路径都经过消毒 get_zim_entries.

服务器卫生

• __version__ 阅读自 importlib.metadata; serverInfo.version 报告了openzim-mcp的实际版本（不再是FastMCP SDK的默认版本）。
• HTTP传输的订阅观察器通过封装的生命周期启动。
• 每次参赛 zim:// 返回libzim的原生MIME（返回占位符）。

简化范围

v1.0.0通过删除没有发挥作用的管理/检查助手，将高级模式工具界面从27减少到21： warm_cache, cache_stats, cache_clear, get_random_entry, diagnose_server_state，以及 resolve_server_conflicts缓存本身仍然存在；明确的管理工具被删除了。多实例冲突跟踪已完全删除-- instance_tracker.py 已经消失了——这意味着HTTP服务器实例可以自由共存，没有配置警告。

审核通过

标记前的端到端审查通过：在错误和诊断响应中收紧路径/PID编辑，锁定 OPTIONS /mcp 在auth之后，修复了瞬态libzim错误导致的缓存中毒问题，在渲染前通过循环检测解决了重定向问题，在标题slug中保留了Unicode（阿拉伯语、中文、西里尔语、日语），进行了限速原子化和拆分 zim_operations.py 进入一个 zim/ 通过mixin类打包。

v0.9.0的新增功能

多存档搜索

search_all 一次查询允许目录中的每个ZIM文件并合并结果——不需要知道哪个存档包含答案。

MCP提示

您可以在MCP感知客户端中以斜线命令调用三个预构建的工作流：

• /research --搜索所有档案，然后钻取热门内容
• /summarize --目录+摘要+关键链接
• /explore --ZIM内容的高层简报

按标题查找条目

find_entry_by_title 通过不区分大小写的匹配将标题（或部分标题）解析为一个或多个条目路径。当你已经知道文章名称时，比全文搜索便宜。

高级用户工具

• walk_namespace --确定性游标分页命名空间迭代（vs。 browse_namespace 哪些样本）
• get_related_articles --给定条目的出站链接图邻居

MCP资源

MCP的首次使用 资源 primitive——客户端的资源浏览器和 @-提及选择器现在可以直接查看ZIM文件：

• zim://files --所有可用ZIM文件的索引
• zim://{name} --ZIM概述（元数据、命名空间、主页预览）
• zim://{name}/entry/{path} *（1.0.0版本新增）* --使用本机MIME类型提供单个条目（客户端必须进行URL编码 / 作为 %2F 在路径段中）

可靠性修复

• 命名空间列表现在可以确定地显示随机抽样可能遗漏的少数命名空间（M、W、X、I）
• 搜索过滤使用流式扫描，而不是严格的1000次点击上限（罕见的mime类型过滤器现在返回以前隐藏的匹配项）
• 错误消息首先按故障模式路由（不再“检查磁盘空间”以查找“找不到条目”）

快速开始

安装

# Install from PyPI as an isolated CLI tool (recommended)
uv tool install openzim-mcp

# Or install into your current environment with pip
pip install openzim-mcp

开发安装

对于贡献者和开发者：

# Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Install dependencies
uv sync

# Install development dependencies
uv sync --dev

准备ZIM文件

从以下网址下载ZIM文件（例如维基百科、维基词典等） Kiwix图书馆 并将它们放置在一个目录中：

mkdir ~/zim-files
# Download ZIM files to ~/zim-files/

运行服务器

# Simple mode (default) - 1 intelligent natural language tool
openzim-mcp /path/to/zim/files
python -m openzim_mcp /path/to/zim/files

# Advanced mode - all 21 specialized tools
openzim-mcp --mode advanced /path/to/zim/files
python -m openzim_mcp --mode advanced /path/to/zim/files

# For development (from source)
uv run python -m openzim_mcp /path/to/zim/files
uv run python -m openzim_mcp --mode advanced /path/to/zim/files

# Or using make (development)
make run ZIM_DIR=/path/to/zim/files

工具模式

OpenZIM MCP支持两种模式：

• 简单模式 （默认）：提供1个智能工具(zim_query)接受自然语言查询
• 高级模式：显示所有21个专用MCP工具，以实现最大控制

MCP配置

将相应的代码段添加到MCP客户端的配置文件中(claude_desktop_config.json光标的MCP设置等）。这 mcpServers Claude Desktop、Cursor和大多数其他MCP客户端都需要包装器。

简单模式（默认）：

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "openzim-mcp",
      "args": ["/path/to/zim/files"]
    }
  }
}

高级模式：

{
  "mcpServers": {
    "openzim-mcp-advanced": {
      "command": "openzim-mcp",
      "args": ["--mode", "advanced", "/path/to/zim/files"]
    }
  }
}

使用Python模块的替代配置：

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "python",
      "args": [
        "-m",
        "openzim_mcp",
        "/path/to/zim/files"
      ]
    }
  }
}

开发（来源）：

{
  "mcpServers": {
    "openzim-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/openzim-mcp",
        "run",
        "python",
        "-m",
        "openzim_mcp",
        "/path/to/zim/files"
      ]
    }
  }
}

发展

运行测试

# Run all tests
make test

# Run tests with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_security.py -v

# Run tests with ZIM test data (comprehensive testing)
make test-with-zim-data

# Run integration tests only
make test-integration

# Run tests that require ZIM test data
make test-requires-zim-data

ZIM测试数据集成

OpenZIM MCP与官方 zim测试套件 使用真实ZIM文件进行全面测试：

# Download essential test files (basic testing)
make download-test-data

# Download all test files (comprehensive testing)
make download-test-data-all

# List available test files
make list-test-data

# Clean downloaded test data
make clean-test-data

测试数据包括：

• 基本文件：用于基本测试的小型ZIM文件
• 真实内容：用于集成测试的实际维基百科/维基教科书内容
• 无效文件：错误处理测试的ZIM文件格式错误
• 特殊情况：嵌入式内容、分割文件和边缘案例

测试文件按类别和优先级自动组织。

代码质量

# Format code
make format

# Run linting
make lint

# Type checking
make type-check

# Run all checks
make check

项目结构

openzim-mcp/
├── openzim_mcp/                # Main package
│   ├── __init__.py             # Package init, exports __version__ via importlib.metadata
│   ├── __main__.py             # Module entry point (`python -m openzim_mcp`)
│   ├── main.py                 # CLI entry point and arg parsing
│   ├── server.py               # MCP server setup, transport selection
│   ├── http_app.py             # Streamable HTTP / SSE transport, auth, CORS, health
│   ├── config.py               # Pydantic config + env var bindings
│   ├── defaults.py             # Default values and tunables
│   ├── security.py             # Path validation, traversal protection, sanitization
│   ├── error_messages.py       # User-facing error message catalog
│   ├── exceptions.py           # Custom exception hierarchy
│   ├── cache.py                # LRU cache with TTL
│   ├── rate_limiter.py         # Per-client + global token-bucket rate limiting
│   ├── content_processor.py    # HTML→text, heading-id, link extraction
│   ├── async_operations.py     # asyncio helpers and timeouts
│   ├── timeout_utils.py        # Timeout primitives
│   ├── subscriptions.py        # MtimeWatcher and SubscriberRegistry
│   ├── simple_tools.py         # Simple-mode `zim_query` tool
│   ├── intent_parser.py        # Natural-language intent parsing
│   ├── types.py                # Shared TypedDicts
│   ├── constants.py            # Shared constants
│   ├── zim_operations.py       # Backward-compat shim re-exporting from zim/ package
│   ├── zim/                    # ZIM access (split from monolithic zim_operations.py)
│   │   ├── __init__.py         # ZimOperations facade composed of mixins
│   │   ├── archive.py          # Archive open/close, file listing, name resolution
│   │   ├── content.py          # Entry retrieval, summaries, batch get
│   │   ├── namespace.py        # Namespace listing, browse, walk
│   │   ├── search.py           # Full-text + suggestion search; cursor pagination
│   │   └── structure.py        # Article structure, links, related articles
│   └── tools/                  # MCP tool registrations
│       ├── __init__.py
│       ├── file_tools.py       # list_zim_files
│       ├── content_tools.py    # get_zim_entry, get_zim_entries
│       ├── search_tools.py     # search_zim_file, search_all, find_entry_by_title
│       ├── navigation_tools.py # browse_namespace, walk_namespace, search_with_filters, get_search_suggestions
│       ├── structure_tools.py  # get_article_structure, extract_article_links, get_entry_summary, get_table_of_contents, get_binary_entry
│       ├── metadata_tools.py   # get_zim_metadata, get_main_page, list_namespaces
│       ├── server_tools.py     # get_server_health, get_server_configuration
│       ├── resource_tools.py   # MCP resources (zim://files, zim://{name}/...)
│       └── prompts.py          # MCP prompts (/research, /summarize, /explore)
├── tests/                      # Test suite (pytest)
├── website/                    # GitHub Pages site source
├── pyproject.toml              # Project configuration
├── Makefile                    # Development commands
├── Dockerfile                  # Multi-stage container build
└── README.md                   # This file

______________________________________________________________________

API 参考

可用工具

list_zim_files-列出允许目录中的所有zim文件

可选参数：

• name_filter （string，默认值：“”）：不区分大小写的子字符串；只返回文件名包含它的文件。空字符串列出了所有内容。有助于缩小大型列表的范围（例如。 "wikipedia", "nginx").

search_zim_file-在zim文件内容中搜索

所需参数：

• zim_file_path （string）：ZIM文件的路径
• query （string）：搜索查询词--必填，除非 cursor 提供。

可选参数：

• limit （整数，默认值：10）：要返回的最大结果数
• offset （整数，默认值：0）：结果的起始偏移量（用于分页）
• cursor （string）：来自先前结果的不透明分页标记 next_cursor。如果提供，则覆盖 offset/limit 将值编码在令牌中，并提供 query 如果没有明确给出。游标仅对其发出的查询有效。

get_zim_entry-获取zim文件中特定条目的详细内容

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：入口路径，例如“A/Some_Tarticle”

可选参数：

• max_content_length （整数，默认值：100000，最小值：1000）：返回内容的最大长度

智能检索功能：

• 自动回退：如果直接路径访问失败，则自动搜索条目并使用找到的确切路径
• 路径映射缓存：缓存成功的路径映射，以提高重复访问的性能
• 增强的错误引导：在找不到条目时提供明确的指导，建议替代方法
• 透明操作：无论路径编码差异如何（空格与下划线、URL编码等），都能无缝工作

get_zim_entries-在一次调用中批量检索多个zim条目

与HTTP传输自然配对，因为往返成本很重要。每批最多50个条目。每个条目独立解析——每个条目的失败不会中止批处理。

所需参数：

• entries （list）：条目路径字符串列表（与 zim_file_path 默认）或列表 {zim_file_path, entry_path} dicts（用于多存档批处理）。限制：每批50个。

可选参数：

• zim_file_path （string）：默认归档路径；如果需要 entries 是裸字符串，当每个dict都有自己的dict时是可选的。
• max_content_length （整数）：每个条目的最大内容长度。

退货： JSON {"results": [...], "succeeded": N, "failed": N}。每个结果包括 index （输入顺序）， success，或者 content 或 error.

笔记： 费率限制按条目收费，而不是按批次收费（反旁路）。

get_zim_metadata-从M个命名空间条目中获取zim文件元数据

所需参数：

• zim_file_path （string）：ZIM文件的路径

退货： 包含ZIM元数据的JSON字符串，包括条目计数、存档信息和元数据条目，如标题、描述、语言、创建者等。

get_min_page-从W命名空间获取主页条目

所需参数：

• zim_file_path （string）：ZIM文件的路径

退货： 主页内容或关于主页条目的信息。

list_namespaces-列出可用命名空间及其条目计数

所需参数：

• zim_file_path （string）：ZIM文件的路径

退货： JSON字符串，包含命名空间信息，其中包含每个命名空间（C、M、W、X等）的条目计数、描述和示例条目。

browse_namespace-使用分页浏览特定命名空间中的条目

所需参数：

• zim_file_path （string）：ZIM文件的路径
• namespace （string）：要浏览的命名空间（C、M、W、X、A、I等）

可选参数：

• limit （整数，默认值：50，范围：1-200）：要返回的最大条目数
• offset （整数，默认值：0）：分页的起始偏移量

退货： JSON字符串，包含带有标题、内容预览和分页信息的命名空间条目。

walk_namespace-确定性游标分页命名空间迭代

不像 browse_namespace （这些样本在大型档案中可能最多200个条目）， walk_namespace 按条目ID扫描存档 cursor 向前的。配对返回 next_cursor 随后，他打电话让其他人步行。 done: true 表示迭代已完成。使用此方法进行详尽的枚举，例如倾倒每个 M/* 元数据条目，或查找路径不遵循常见模式的条目。

所需参数：

• zim_file_path （string）：ZIM文件的路径
• namespace （string）：要遍历的命名空间（C、M、W、X、A、I等）

可选参数：

• cursor （整数，默认值：0）：要从中恢复的条目ID
• limit （整数，默认值：200，范围：1–500）：每页最大条目数

退货： JSON格式 entries, next_cursor，以及 done 旗帜。

search_with_filters-使用高级过滤器在ZIM文件内容中搜索

所需参数：

• zim_file_path （string）：ZIM文件的路径
• query （string）：搜索查询词

可选参数：

• namespace （string）：可选命名空间过滤器（C、M、W、X等）
• content_type （string）：可选内容类型过滤器（text/html、text/plain等）
• limit （整数，默认值：10，范围：1-100）：要返回的最大结果数
• offset （整数，默认值：0）：分页的起始偏移量

退货： 使用命名空间和内容类型信息筛选搜索结果。

search_all-在允许的目录中搜索每个ZIM文件

返回每个文件的合并结果，因此调用者不需要知道哪个文件包含信息。无法搜索的文件（已损坏，没有全文索引）将被跳过，而不会中止其余部分。

所需参数：

• query （string）：搜索查询词

可选参数：

• limit_per_file （整数，默认值：5，范围：1–50）：每个ZIM文件的最大点击次数
• limit （整数）：别名 limit_per_file如果两者都提供， limit_per_file 获胜。

退货： JSON包含每个文件的结果组以及搜索到的文件、有结果的文件和失败的文件的计数。

find_entry_by_title-将标题解析为一个或多个条目路径

当调用者知道文章标题时，比全文搜索便宜。尝试精确归一化 C/ 首先匹配（快速路径），然后回退到libzim的标题索引建议搜索。

所需参数：

• zim_file_path （string）：ZIM文件的路径（除非 cross_file=true)
• title （string）：要解析的标题或部分标题（不区分大小写）

可选参数：

• cross_file （boolean，默认值：false）：如果为true，则搜索所有允许的ZIM文件
• limit （整数，默认值：10，范围：1–50）：返回的最大结果

退货： JSON格式 query，排名 results, fast_path_hit 旗，以及 files_searched 计数。

get_search_suggestions-获取搜索建议并自动完成

所需参数：

• zim_file_path （string）：ZIM文件的路径
• partial_query （字符串）：部分搜索查询（至少2个字符）

可选参数：

• limit （整数，默认值：10，范围：1-50）：要返回的最大建议数

退货： JSON字符串，包含基于文章标题和内容的搜索建议。

get_article_structure-提取文章结构和元数据

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：入口路径，例如“C/Some_Tarticle”

退货： 包含文章结构的JSON字符串，包括标题、章节、元数据和字数。

extract_article_links-从文章中提取内部和外部链接

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：入口路径，例如“C/Some_Tarticle”

退货： JSON字符串，包含带有标题和元数据的分类链接（内部、外部、媒体）。

get_lated_articles-通过出站链接查找与给定条目相关的文章

组成 extract_article_links 并对内部链接进行重复数据消除，最多可恢复到 limit 出境目标。（入站发现已被删除——它需要一个有界的完整存档扫描，对于交互式使用来说成本太高；请改用全文搜索。）

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：源条目，例如“C/Some_Tarticle”

可选参数：

• limit （整数，默认值：10，范围：1–100）：最大结果

退货： JSON格式 results.

get_entry_summary-获取简洁的文章摘要

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：入口路径，例如“C/Some_Tarticle”

可选参数：

• max_words （整数，默认值：200，范围：10-1000）：摘要中的最大字数

退货： JSON字符串，包含从文章开头段落中提取的简明摘要，元数据包括标题、字数和截断状态。

特征：

• 在删除信息框、导航栏和侧栏的同时提取开头段落
• 提供快速文章概述，无需加载完整内容
• 有助于LLM在决定阅读更多之前了解文章背景

get_table_of_contents-提取分层目录

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：入口路径，例如“C/Some_Tarticle”

退货： JSON字符串，包含文章标题的层次树结构（h1-h6），适用于导航和内容概述。

特征：

• 嵌套子级的层次树结构
• 包括标题级别、文本和锚点ID
• 提供航向计数和最大深度统计信息
• 使LLM能够直接导航到特定部分

get_binary_entry-从ZIM条目中检索二进制内容

所需参数：

• zim_file_path （string）：ZIM文件的路径
• entry_path （string）：输入路径，例如“I/image.png”或“I/document.pdf”

可选参数：

• max_size_bytes （整数）：返回内容的最大大小（默认值：10MB）。大于此值的内容将仅返回元数据。
• include_data （boolean）：如果为true（默认），则包含base64编码的数据。设置为false仅检索元数据。

退货：

JSON字符串包含：

• path：ZIM文件中的入口路径
• title：条目标题
• mime_type：内容类型（例如“应用程序/pdf”、“图像/png”）
• size：大小（字节）
• size_human：人类可读大小（例如“1.5 MB”）
• encoding：包含数据时为“base64”，否则为null
• data：Base64编码内容（如果include_data=true且小于大小限制）
• truncated：布尔值，指示内容是否超过大小限制

使用案例：

• 检索PDF以使用PDF解析工具进行处理
• 为视觉模型或OCR工具提取图像
• 获取用于转录服务的视频/音频文件
• 使用专门的内容处理器启用多代理工作流

______________________________________________________________________

示例

正在列出ZIM文件

{
  "name": "list_zim_files"
}

答复：

Found 1 ZIM files in 1 directories:

[
  {
    "name": "wikipedia_en_100_2025-08.zim",
    "path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "directory": "C:\\zim",
    "size": "310.77 MB",
    "modified": "2025-09-11T10:20:50.148427"
  }
]

正在搜索ZIM文件

{
  "name": "search_zim_file",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "query": "biology",
    "limit": 3
  }
}

答复：

Found 51 matches for "biology", showing 1-3:

## 1. Taxonomy (biology)
Path: Taxonomy_(biology)
Snippet: #  Taxonomy (biology) Part of a series on
---
Evolutionary biology
Darwin's finches by John Gould

  * Index
  * Introduction
  * [Main](Evolution "Evolution")
  * Outline

## 2. Protein
Path: Protein
Snippet: #  Protein A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

## 3. Ant
Path: Ant
Snippet: #  Ant Ants
Temporal range: Late Aptian – Present
---
Fire ants
[Scientific classification](Taxonomy_\(biology\) "Taxonomy \(biology\)")
Kingdom:  | [Animalia](Animal "Animal")
Phylum:  | [Arthropoda](Arthropod "Arthropod")
Class:  | [Insecta](Insect "Insect")
Order:  | Hymenoptera
Infraorder:  | Aculeata
Superfamily:  |
Latreille, 1809[1]
Family:  |
Latreille, 1809

获取ZIM条目

{
  "name": "get_zim_entry",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "Protein"
  }
}

答复：

# Protein

Path: Protein
Type: text/html
## Content

#  Protein

A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

**Proteins** are large biomolecules and macromolecules that comprise one or more long chains of amino acid residues. Proteins perform a vast array of functions within organisms, including catalysing metabolic reactions, DNA replication, responding to stimuli, providing structure to cells and organisms, and transporting molecules from one location to another. Proteins differ from one another primarily in their sequence of amino acids, which is dictated by the nucleotide sequence of their genes, and which usually results in protein folding into a specific 3D structure that determines its activity.

A linear chain of amino acid residues is called a polypeptide. A protein contains at least one long polypeptide. Short polypeptides, containing less than 20–30 residues, are rarely considered to be proteins and are commonly called peptides.

... [Content truncated, total of 56,202 characters, only showing first 1,500 characters] ...

智能检索在行动

示例：自动路径解析

{
  "name": "get_zim_entry",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "C/Test Article"
  }
}

响应（显示智能检索工作）：

# Test Article

Requested Path: C/Test Article
Actual Path: C/Test_Article
Type: text/html

## Content

# Test Article

This article demonstrates the smart retrieval system automatically handling
path encoding differences. The system tried "C/Test Article" directly,
then automatically searched and found "C/Test_Article".

... [Content continues] ...

get_server_health-获取服务器运行状况和统计信息

无需参数。

退货：

• 总体状况(healthy / warning / error)
• 缓存性能指标（命中率、未命中率、命中率、大小）
• 目录和ZIM文件可访问性检查
• 建议和警告
• 山宁泰配置摘要

示例响应：

{
  "timestamp": "2026-05-03T10:42:11.123456",
  "status": "healthy",
  "server_name": "openzim-mcp",
  "uptime_info": {
    "process_id": "[REDACTED]",
    "started_at": "2026-05-03T10:30:00"
  },
  "configuration": {
    "allowed_directories": 1,
    "cache_enabled": true,
    "config_hash": "abc12345..."
  },
  "cache_performance": {
    "enabled": true,
    "size": 4,
    "max_size": 100,
    "hit_rate": 0.62
  },
  "health_checks": {
    "directories_accessible": 1,
    "zim_files_found": 3,
    "permissions_ok": true
  },
  "recommendations": [],
  "warnings": []
}

get_server_configuration-获取详细的服务器配置

无需参数。

退货： 全面的服务器配置和诊断。敏感字段（PID、原始文件系统路径）被编辑/净化——诊断输出旨在安全地粘贴到错误报告中。

示例响应：

{
  "configuration": {
    "server_name": "openzim-mcp",
    "allowed_directories": ["[REDACTED]/zim"],
    "allowed_directories_count": 1,
    "cache_enabled": true,
    "cache_max_size": 100,
    "cache_ttl_seconds": 3600,
    "content_max_length": 100000,
    "content_snippet_length": 1000,
    "search_default_limit": 10,
    "config_hash": "abc12345...",
    "server_pid": "[REDACTED]"
  },
  "diagnostics": {
    "validation_status": "ok",
    "warnings": [],
    "recommendations": []
  },
  "timestamp": "2026-05-03T10:42:11.123456"
}

其他搜索示例

计算机相关搜索：

{
  "name": "search_zim_file",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "query": "computer",
    "limit": 2
  }
}

答复：

Found 39 matches for "computer", showing 1-2:

## 1. Video game
Path: Video_game
Snippet: #  Video game First-generation _Pong_ console at the Computerspielemuseum Berlin
---
Platforms

## 2. Protein
Path: Protein
Snippet: #  Protein A representation of the 3D structure of the protein myoglobin showing turquoise α-helices. This protein was the first to have its structure solved by X-ray crystallography. Toward the right-center among the coils, a prosthetic group called a heme group (shown in gray) with a bound oxygen molecule (red).

获取详细内容：

{
  "name": "get_zim_entry",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "Evolution",
    "max_content_length": 1500
  }
}

答复：

# Evolution

Path: Evolution
Type: text/html
## Content

#  Evolution

Part of the Biology series on
---
****
Mechanisms and processes

  * Adaptation
  * Genetic drift
  * Gene flow
  * History of life
  * Maladaptation
  * Mutation
  * Natural selection
  * Neutral theory
  * Population genetics
  * Speciation

... [Content truncated, total of 110,237 characters, only showing first 1,500 characters] ...

高级知识检索示例

获取ZIM元数据：

{
  "name": "get_zim_metadata",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim"
  }
}

答复：

{
  "entry_count": 100000,
  "all_entry_count": 120000,
  "article_count": 80000,
  "media_count": 20000,
  "metadata_entries": {
    "Title": "Wikipedia (English)",
    "Description": "Wikipedia articles in English",
    "Language": "eng",
    "Creator": "Kiwix",
    "Date": "2025-08-15"
  }
}

浏览命名空间：

{
  "name": "browse_namespace",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "namespace": "C",
    "limit": 5,
    "offset": 0
  }
}

答复：

{
  "namespace": "C",
  "total_in_namespace": 80000,
  "offset": 0,
  "limit": 5,
  "returned_count": 5,
  "has_more": true,
  "entries": [
    {
      "path": "C/Biology",
      "title": "Biology",
      "content_type": "text/html",
      "preview": "Biology is the scientific study of life..."
    }
  ]
}

筛选搜索：

{
  "name": "search_with_filters",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "query": "evolution",
    "namespace": "C",
    "content_type": "text/html",
    "limit": 3
  }
}

获取文章结构：

{
  "name": "get_article_structure",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "C/Evolution"
  }
}

答复：

{
  "title": "Evolution",
  "path": "C/Evolution",
  "content_type": "text/html",
  "headings": [
    {"level": 1, "text": "Evolution", "id": "evolution"},
    {"level": 2, "text": "History", "id": "history"},
    {"level": 2, "text": "Mechanisms", "id": "mechanisms"}
  ],
  "sections": [
    {
      "title": "Evolution",
      "level": 1,
      "content_preview": "Evolution is the change in heritable traits...",
      "word_count": 150
    }
  ],
  "word_count": 5000
}

获取文章摘要：

{
  "name": "get_entry_summary",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "C/Evolution",
    "max_words": 100
  }
}

答复：

{
  "title": "Evolution",
  "path": "C/Evolution",
  "content_type": "text/html",
  "summary": "Evolution is the change in heritable characteristics of biological populations over successive generations. These characteristics are the expressions of genes, which are passed from parent to offspring during reproduction...",
  "word_count": 100,
  "is_truncated": true
}

获取目录：

{
  "name": "get_table_of_contents",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "entry_path": "C/Evolution"
  }
}

答复：

{
  "title": "Evolution",
  "path": "C/Evolution",
  "content_type": "text/html",
  "toc": [
    {
      "level": 1,
      "text": "Evolution",
      "id": "evolution",
      "children": [
        {
          "level": 2,
          "text": "History of evolutionary thought",
          "id": "history",
          "children": []
        },
        {
          "level": 2,
          "text": "Mechanisms",
          "id": "mechanisms",
          "children": []
        }
      ]
    }
  ],
  "heading_count": 15,
  "max_depth": 4
}

获取搜索建议：

{
  "name": "get_search_suggestions",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "partial_query": "bio",
    "limit": 5
  }
}

答复：

{
  "partial_query": "bio",
  "suggestions": [
    {"text": "Biology", "path": "C/Biology", "type": "title_start_match"},
    {"text": "Biochemistry", "path": "C/Biochemistry", "type": "title_start_match"},
    {"text": "Biodiversity", "path": "C/Biodiversity", "type": "title_start_match"}
  ],
  "count": 3
}

服务器管理和诊断示例

获取服务器运行状况：

{
  "name": "get_server_health"
}

答复：

{
  "status": "healthy",
  "server_name": "openzim-mcp",
  "uptime_info": {
    "process_id": "[REDACTED]",
    "started_at": "2026-05-03T10:30:00"
  },
  "cache_performance": {
    "enabled": true,
    "size": 15,
    "max_size": 100,
    "hit_rate": 0.85
  }
}

______________________________________________________________________

ZIM条目检索最佳实践

智能检索系统

OpenZIM MCP实现了一个智能条目检索系统，可以自动处理ZIM文件中常见的路径编码不一致：

工作原理：

1. 直接访问优先：尝试使用与给定路径完全相同的路径检索条目
2. 自动回退：如果直接访问失败，则使用各种搜索词自动搜索条目
3. 路径映射缓存：缓存成功的路径映射，以提高重复访问的性能
4. 增强的错误引导：当找不到条目时提供明确的指导

LLM用户的好处：

• 透明操作：无需了解ZIM路径编码的复杂性
• 单一工具调用：消除了手动搜索优先方法的需要
• 可靠的结果：不同路径格式（空格与下划线、URL编码等）的一致成功
• 性能优化：缓存映射提高了重复访问速度

自动处理的示例场景：

• C/Test Article → C/Test_Article （空格到下划线转换）
• C/Café → C/Caf%C3%A9 （URL编码差异）
• A/Some-Page → A/Some_Page （连字符到下划线的转换）

使用建议

对于直接入口访问：

{
  "name": "get_zim_entry",
  "arguments": {
    "zim_file_path": "/path/to/file.zim",
    "entry_path": "C/Article_Name"
  }
}

当未找到条目时： 系统将自动提供指导：

Entry not found: 'A/Article_Name'.
The entry path may not exist in this ZIM file.
Try using search_zim_file() to find available entries,
or browse_namespace() to explore the file structure.

______________________________________________________________________

重要注意事项和限制

内容长度要求

• 这 max_content_length 参数 get_zim_entry 必须至少包含1000个字符
• 超过指定限制的内容将被截断，并显示总字符数

搜索行为

• 搜索结果可能包括在各种上下文中包含搜索词的文章
• 结果按相关性排序，但可能并不总是与搜索词的主要含义直接相关
• 搜索片段提供了内容的预览，但可能不会显示搜索词出现的确切位置

文件格式支持

• 目前支持ZIM文件（Zeno IMprovide格式）
• 用维基百科ZIM文件测试（例如。， wikipedia_en_100_2025-08.zim)
• 文件路径必须以JSON格式正确转义（使用 \\ 对于Windows路径）

______________________________________________________________________

配置

OpenZIM MCP支持通过环境变量进行配置 OPENZIM_MCP_ 前缀：

# Cache configuration
export OPENZIM_MCP_CACHE__ENABLED=true
export OPENZIM_MCP_CACHE__MAX_SIZE=200
export OPENZIM_MCP_CACHE__TTL_SECONDS=7200

# Content configuration
export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000
export OPENZIM_MCP_CONTENT__SNIPPET_LENGTH=2000
export OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT=20

# Logging configuration
export OPENZIM_MCP_LOGGING__LEVEL=DEBUG
export OPENZIM_MCP_LOGGING__FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"

# Server configuration
export OPENZIM_MCP_SERVER_NAME=my_openzim_mcp_server

配置选项

______________________________________________________________________

安全功能

• 路径横向保护：安全路径验证可防止在允许的目录之外进行访问
• 输入消毒：所有用户输入都经过验证和消毒
• 资源管理：正确清理ZIM归档资源
• 错误处理：山宁泰错误消息防止信息泄露
• 类型安全：完整类型注释可防止与类型相关的漏洞

______________________________________________________________________

性能特点

• 智能高速缓存：带有TTL的LRU缓存，用于频繁访问的内容
• 资源池：高效的ZIM归档管理
• 优化内容处理：快速HTML到文本转换
• 延迟加载：仅在需要时初始化组件
• 内存管理：适当的清理和资源管理

______________________________________________________________________

测试

该项目包括使用模拟数据和真实ZIM文件进行覆盖率超过80%的全面测试：

测试类别

• 单元测试：使用模拟进行单个组件测试
• 集成测试：使用真实ZIM文件进行端到端功能测试
• 安全测试：路径遍历和输入验证测试
• 性能测试：缓存和资源管理测试
• 格式兼容性：使用各种ZIM文件格式和版本进行测试
• 错误处理：使用无效和格式错误的ZIM文件进行测试

测试基础设施

OpenZIM MCP使用混合测试方法：

1. 基于模拟的测试：使用模拟的libzim组件进行快速单元测试
2. 真实ZIM文件测试：使用官方zim测试套件文件进行集成测试
3. 自动测试数据管理：根据需要下载和组织测试文件

测试数据源

• 内置测试数据：存储库中包含的基本测试文件
• zim测试套件集成：OpenZIM项目的官方测试文件
• 环境变量支持: ZIM_TEST_DATA_DIR 用于自定义测试数据位置

# Run tests with coverage report
make test-cov

# View coverage report
open htmlcov/index.html

# Run comprehensive tests with real ZIM files
make test-with-zim-data

测试标记

使用pytest标记组织测试：

• @pytest.mark.requires_zim_data：需要ZIM测试数据文件的测试
• @pytest.mark.integration：集成测试
• @pytest.mark.slow：长时间运行测试

______________________________________________________________________

监控

OpenZIM MCP提供内置监控功能：

• 健康检查：服务器运行状况和状态监视
• 缓存指标：缓存命中率和性能统计信息
• 结构化日志记录：JSON格式的日志，便于解析
• 错误跟踪：全面的错误记录和跟踪

______________________________________________________________________

版本控制

自动发布

版本升级和发布是基于以下内容自动进行的 约定式提交:

• feat: -新功能（小版本凹凸）
• fix: -Bug修复（补丁版本碰撞）
• feat!: 或 BREAKING CHANGE: -重大变化（主要版本碰撞）
• perf: -性能改进（补丁版本碰撞）
• docs:, style:, refactor:, test:, chore: -无版本冲突

发布过程

该项目使用 改进的统一发布系统 自动验证：

1. 自动 （推荐）：推送常规提交→ 发布请创建PR→ 合并PR→ 自动释放
2. 手册：使用GitHub Actions UI直接控制发布
3. 紧急情况：直接推送标签以进行关键修复

主要特点：

• 零接触释放 从主要分支
• 自动版本同步 验证
• 综合测试 每次发布前
• 改进了错误处理 以及回滚功能
• 分支保护 防止释放中断

发布流程在 和 .

提交消息格式

[optional scope]: 

[optional body]

[optional footer(s)]

示例：

feat: add search suggestions endpoint
fix: resolve path traversal vulnerability
feat!: change API response format
docs: update installation instructions

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试(make check)
5. 使用常规提交消息 (git commit -m 'feat: add amazing feature')
6. 推到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

开发指南

• 遵循PEP 8风格指南
• 为所有函数添加类型提示
• 为新功能编写测试
• 根据需要更新文档
• 使用常规提交消息 用于自动版本控制
• 提交前确保所有测试通过

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

致谢

• Kiwix 用于ZIM格式和libzim库
• 主控程序 对于模型上下文协议
• 该项目中使用的优秀库的开源社区

______________________________________________________________________

由以下材料制成❤️ 通过 Cameron Rye