开放锌-MCP

Name: 开放锌-MCP
Author: cameronrye

作者：cameronrye10 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

OpenZIM MCP 服务器

现在支持双模式！ 可以选择简单模式（1个智能自然语言工具，默认）或高级模式（15个专业工具），以匹配您的大语言模型的能力。

为大语言模型智能

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

为什么大语言模型喜欢 OpenZIM MCP：

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

无论您是构建研究助手、知识聊天机器人还是内容分析系统，OpenZIM MCP 都能为您提供大语言模型所需的结构化访问模式，解锁离线知识存档的全部潜力。再也不用在原始文本转储中摸索了！

OpenZIM MCP 是一个现代、安全且高性能的 MCP（模型上下文协议）服务器，它使 AI 模型能够访问和搜索 ZIM 格式的知识库，即使在离线状态下也能使用。

ZIM（Zeno 改进版）是由 openZIM 项目开发的一种开放文件格式，专门用于离线存储和访问网站内容。该格式使用 Zstandard 压缩（自 2021 年起默认使用）支持高压缩率，并允许快速全文搜索，使其非常适合存储整个维基百科内容和其他大型参考材料，以相对紧凑的文件形式。openZIM 项目由 Wikimedia CH 赞助，并得到 Wikimedia 基金会的支持，确保该格式继续发展并被采用，特别是在没有可靠互联网连接的环境中进行离线知识访问。

功能

双模式支持：可以选择简单模式（1个智能自然语言工具，默认）或高级模式（15个专业工具）
安全第一：全面的输入验证和路径遍历保护
高性能：智能缓存和优化的 ZIM 文件操作
智能检索：从直接访问到基于搜索的检索的自动回退，确保可靠的条目访问
经过充分测试：超过90%的测试覆盖率，具有全面的测试套件
现代架构：模块化设计，依赖注入
类型安全：在整个代码库中添加完整的类型注释
可配置：灵活配置，带有验证
可观测性：结构化日志和健康监控

快速开始

安装

# 从 PyPI 安装（推荐）
pip install openzim-mcp

开发安装

对于贡献者和开发者：

# 克隆仓库
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# 安装依赖
uv sync

# 安装开发依赖
uv sync --dev

准备 ZIM 文件

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

mkdir ~/zim-files
# 将 ZIM 文件下载到 ~/zim-files/

运行服务器

# 简单模式（默认）- 1个智能自然语言工具
openzim-mcp /path/to/zim/files
python -m openzim_mcp /path/to/zim/files

# 高级模式 - 所有15个专业工具
openzim-mcp --mode advanced /path/to/zim/files
python -m openzim_mcp --mode advanced /path/to/zim/files

# 开发（从源码）
uv run python -m openzim_mcp /path/to/zim/files
uv run python -m openzim_m_ cp --mode advanced /path/to/zim/files

# 或使用 make（开发）
make run ZIM_DIR=/path/to/zim/files

工具模式

OpenZIM MCP 支持两种模式：

简单模式（默认）：提供1个智能工具（zim_query），接受自然语言查询
高级模式：暴露所有15个专业 MCP 工具，实现最大控制

详见简单模式指南获取详细信息。

MCP 配置

简单模式（默认）：

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

高级模式：

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

使用 Python 模块的替代配置：

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

对于开发（从源码）：

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

开发

运行测试

# 运行所有测试
make test

# 运行带覆盖率的测试
make test-cov

# 运行特定测试文件
uv run pytest tests/test_security.py -v

# 运行带 ZIM 测试数据的测试（全面测试）
make test-with-zim-data

# 仅运行集成测试
make test-integration

# 运行需要 ZIM 测试数据的测试
make test-requires-zim-data

ZIM 测试数据集成

OpenZIM MCP 与官方 zim-testing-suite 集成，进行全面测试，使用真实的 ZIM 文件：

# 下载基本测试文件（基本测试）
make download-test-data

# 下载所有测试文件（全面测试）
make download-test-data-all

# 列出可用的测试文件
make list-test-data

# 清理下载的测试数据
make clean-test-data

测试数据包括：

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

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

代码质量

# 格式化代码
make format

# 运行代码检查
make lint

# 类型检查
make type-check

# 运行所有检查
make check

项目结构

openzim-mcp/
├── openzim_mcp/             # 主包
│   ├── __init__.py        # 包初始化
│   ├── __main__.py        # 模块入口点
│   ├── main.py            # 主入口点
│   ├── server.py          # MCP 服务器实现
│   ├── config.py          # 配置管理
│   ├── security.py        # 安全性和验证
│   ├── cache.py           # 缓存功能
│   ├── content_processor.py # 内容处理
│   ├── zim_operations.py  # ZIM 文件操作
│   ├── exceptions.py      # 自定义异常
│   └── constants.py       # 应用常量
├── tests/                 # 测试套件
├── pyproject.toml        # 项目配置
├── Makefile              # 开发命令
└── README.md             # 本文档

API 参考

可用工具

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

无需参数。

search_zim_file - 在 ZIM 文件内容中搜索

必需参数：

zim_file_path（字符串）：ZIM 文件路径
query（字符串）：搜索查询词

可选参数：

limit（整数，默认值：10）：返回的最大结果数量
offset（整数，默认值：0）：结果的起始偏移量（用于分页）

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径
entry_path（字符串）：条目路径，例如 'A/Some_Article'

可选参数：

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

智能检索特性：

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

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径

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

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径

返回： 主页面内容或关于主页面条目的信息。

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径

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

browse_namespace - 浏览特定命名空间中的条目，带有分页

必需参数：

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

可选参数：

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

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

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径
query（字符串）：搜索查询词

可选参数：

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

返回： 带有命名空间和内容类型信息的过滤搜索结果。

get_search_suggestions - 获取搜索建议和自动完成功能

必需参数：

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

可选参数：

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

返回： 基于文章标题和内容的搜索建议的 JSON 字符串。

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径
entry_path（字符串）：条目路径，例如 'C/Some_Article'

返回： 包含文章结构的 JSON 字符串，包括标题、章节、元数据和字数统计。

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

必需参数：

zim_file_path（字符串）：ZIM 文件路径
entry_path（字符串）：条目路径，例如 'C/Some_Article'

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

示例

列出 ZIM 文件

{
  "name": "list_zim_files"
}

响应：

找到 1 个 ZIM 文件在 1 个目录中：

[
  {
    "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
  }
}

响应：

找到 51 个匹配项 "biology"，显示 1-3：

## 1. 分类学（生物学）
路径：Taxonomy_(biology)
摘要：# 分类学（生物学）系列的一部分
---
进化生物学
达尔文的雀鸟由约翰·古尔德绘制