Openzim MCP

🚀 OpenZIM MCP Server

OpenZIM MCP 是一款現代、安全且高性能的 MCP（Model Context Protocol）服務器，它能讓 AI 模型離線訪問和搜索 ZIM 格式 的知識庫。該工具將靜態的 ZIM 存檔轉變為適用於大語言模型的動態知識引擎，為大語言模型提供智能、結構化的訪問方式，使其能有效瀏覽和理解海量的知識倉庫。

項目徽章

• 構建與質量：
  • 
  • 
  • 
  • 
• 包與版本：
  • 
  • 
  • 
  • 
• 代碼質量與標準：
  • 
  • 
  • 
  • 
• 社區與貢獻：
  • 
  • 
  • 
  • 

✨ 主要特性

• 🔒 安全至上：全面的輸入驗證和路徑遍歷保護。
• ⚡ 高性能：智能緩存和優化的 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/ 目錄下

運行服務器

# 使用控制檯腳本（在使用 pip 安裝後）
openzim-mcp /path/to/zim/files

# 或者使用模塊
python -m openzim_mcp /path/to/zim/files

# 開發環境（從源代碼運行）
uv run python -m openzim_mcp /path/to/zim/files

# 或者使用 make（開發環境）
make run ZIM_DIR=/path/to/zim/files

MCP 配置

添加到你的 MCP 客戶端配置中：

{
  "openzim-mcp": {
    "command": "openzim-mcp",
    "args": ["/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"
    ]
  }
}

📚 詳細文檔

可用工具

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）：返回內容的最大長度。

智能檢索特性：

• 自動回退：如果直接路徑訪問失敗，會自動搜索該條目並使用找到的精確路徑。
• 路徑映射緩存：緩存成功的路徑映射，以提高重複訪問的性能。
• 增強的錯誤指導：當找不到條目時，提供清晰的指導。
• 透明操作：無論路徑編碼差異（空格與下劃線、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（整數，默認值：10，範圍：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 個目錄中找到 1 個 ZIM 文件：

[
  {
    "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)
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.

... [內容截斷，總共 56,202 個字符，僅顯示前 1,500 個字符] ...

智能檢索示例

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

響應（展示智能檢索工作情況）：

# Test Article

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

## Content

# Test Article

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

... [內容繼續] ...

get_server_health - 獲取服務器健康狀況和統計信息

無需參數。

返回值：

• 服務器狀態和性能指標。
• 緩存統計信息。
• 配置信息。
• 實例跟蹤信息。
• 衝突檢測結果。

示例響應：

{
  "status": "healthy",
  "server_name": "openzim-mcp",
  "allowed_directories": 1,
  "cache": {
    "enabled": true,
    "size": 1,
    "max_size": 100,
    "ttl_seconds": 3600
  },
  "instance_tracking": {
    "active_instances": 1,
    "conflicts_detected": 0
  }
}

get_server_configuration - 獲取詳細的服務器配置

無需參數。

返回值： 全面的服務器配置，包括診斷信息、驗證結果和衝突檢測。

示例響應：

{
  "configuration": {
    "server_name": "openzim-mcp",
    "allowed_directories": ["/path/to/zim/files"],
    "cache_enabled": true,
    "config_hash": "abc123...",
    "server_pid": 12345
  },
  "diagnostics": {
    "validation_status": "healthy",
    "conflicts_detected": [],
    "warnings": [],
    "recommendations": []
  }
}

diagnose_server_state - 全面的服務器診斷

無需參數。

返回值： 詳細的診斷信息，包括實例衝突、配置驗證、文件可訪問性檢查和可操作的建議。

示例響應：

{
  "status": "healthy",
  "server_info": {
    "pid": 12345,
    "server_name": "openzim-mcp",
    "config_hash": "abc123..."
  },
  "conflicts": [],
  "issues": [],
  "recommendations": ["Server appears to be running normally"],
  "environment_checks": {
    "directories_accessible": true,
    "cache_functional": true
  }
}

resolve_server_conflicts - 識別和解決服務器衝突

無需參數。

返回值： 衝突解決的結果，包括清理操作和建議。

示例響應：

{
  "status": "success",
  "cleanup_results": {
    "stale_instances_removed": 2
  },
  "conflicts_found": [],
  "actions_taken": ["Removed 2 stale instance files"],
  "recommendations": ["No active conflicts detected"]
}

其他搜索示例

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

響應：

找到 39 個與 "computer" 匹配的結果，顯示 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

... [內容截斷，總共 110,237 個字符，僅顯示前 1,500 個字符] ...

高級知識檢索示例

{
  "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_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": 12345,
    "started_at": "2025-09-14T10:30:00"
  },
  "cache_performance": {
    "enabled": true,
    "size": 15,
    "max_size": 100,
    "hit_rate": 0.85
  },
  "instance_tracking": {
    "active_instances": 1,
    "conflicts_detected": 0
  }
}

{
  "name": "diagnose_server_state"
}

響應：

{
  "status": "healthy",
  "server_info": {
    "pid": 12345,
    "server_name": "openzim-mcp",
    "config_hash": "abc123def456..."
  },
  "conflicts": [],
  "issues": [],
  "recommendations": ["Server appears to be running normally. No issues detected."],
  "environment_checks": {
    "directories_accessible": true,
    "cache_functional": true,
    "zim_files_found": 5
  }
}

{
  "name": "resolve_server_conflicts"
}

響應：

{
  "status": "success",
  "cleanup_results": {
    "stale_instances_removed": 2,
    "files_cleaned": ["/home/user/.openzim_mcp_instances/server_99999.json"]
  },
  "conflicts_found": [],
  "actions_taken": ["Removed 2 stale instance files"],
  "recommendations": ["No active conflicts detected after cleanup"]
}

🎯 ZIM 條目檢索最佳實踐

智能檢索系統

OpenZIM MCP 實現了一個智能條目檢索系統，該系統可以自動處理 ZIM 文件中常見的路徑編碼不一致問題：

• 工作原理：
  1. 優先直接訪問：嘗試使用提供的路徑精確檢索條目。
  2. 自動回退：如果直接訪問失敗，會自動使用各種搜索詞搜索該條目。
  3. 路徑映射緩存：緩存成功的路徑映射，以提高重複訪問的性能。
  4. 增強的錯誤指導：當找不到條目時，提供清晰的指導。
• 對大語言模型用戶的好處：
  • 透明操作：無需瞭解 ZIM 路徑編碼的複雜性。
  • 單次工具調用：無需手動先進行搜索。
  • 可靠結果：在不同的路徑格式（空格與下劃線、URL 編碼等）下都能保持一致的成功率。
  • 性能優化：緩存的映射提高了重複訪問的速度。
• 自動處理的示例場景：
  • A/Test Article → A/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": "A/Article_Name"
  }
}

條目未找到時： 系統將自動提供指導：

條目未找到：'A/Article_Name'。
該條目路徑可能不存在於這個 ZIM 文件中。
嘗試使用 search_zim_file() 查找可用條目，
或使用 browse_namespace() 探索文件結構。

⚠️ 重要注意事項和限制

內容長度要求

• get_zim_entry 的 max_content_length 參數必須至少為 1000 個字符。
• 超過指定限制的內容將被截斷，並顯示總字符數。

搜索行為

• 搜索結果可能包括在各種上下文中包含搜索詞的文章。
• 結果按相關性排序，但可能並不總是與搜索詞的主要含義直接相關。
• 搜索片段提供了內容的預覽，但可能不顯示搜索詞的確切位置。

文件格式支持

• 目前支持 ZIM 文件（Zeno IMproved 格式）。
• 已使用維基百科 ZIM 文件（例如 wikipedia_en_100_2025-08.zim）進行測試。
• 文件路徑在 JSON 中必須正確轉義（Windows 路徑使用 \\）。

🔄 多服務器實例管理

實例跟蹤特性

• 自動實例註冊：每個服務器實例都會自動使用唯一的進程 ID 和配置哈希進行註冊。
• 衝突檢測：檢測多個具有不同配置的服務器訪問相同目錄的情況。
• 陳舊實例清理：自動識別並清理已終止進程的孤立實例文件。
• 配置驗證：確保所有服務器實例使用兼容的配置。

衝突類型

1. 配置不匹配：多個具有不同設置的服務器訪問相同的目錄。
2. 多個實例：多個服務器同時運行（可能會導致混淆）。
3. 陳舊實例：已終止進程的孤立實例文件。

自動衝突警告

當檢測到問題時，OpenZIM MCP 會自動在搜索結果和文件列表中包含衝突警告：

🔍 **檢測到服務器衝突**
⚠️ 與服務器 PID 12345 的配置不匹配。搜索結果可能不一致。
💡 使用 'resolve_server_conflicts()' 解決這些問題。

最佳實踐

• 定期使用 diagnose_server_state() 檢查衝突。
• 運行 resolve_server_conflicts() 清理陳舊實例。
• 當訪問共享目錄時，確保所有服務器實例使用相同的配置。
• 使用 get_server_health() 監控服務器健康狀況，獲取實例跟蹤信息。

🔧 配置

OpenZIM MCP 支持通過帶有 OPENZIM_MCP_ 前綴的環境變量進行配置：

# 緩存配置
export OPENZIM_MCP_CACHE__ENABLED=true
export OPENZIM_MCP_CACHE__MAX_SIZE=200
export OPENZIM_MCP_CACHE__TTL_SECONDS=7200

# 內容配置
export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000
export OPENZIM_MCP_CONTENT__SNIPPET_LENGTH=2000
export OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT=20

# 日誌配置
export OPENZIM_MCP_LOGGING__LEVEL=DEBUG
export OPENZIM_MCP_LOGGING__FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"

# 服務器配置
export OPENZIM_MCP_SERVER_NAME=my_openzim_mcp_server

配置選項

設置	默認值	描述
OPENZIM_MCP_CACHE__ENABLED	true	啟用/禁用緩存
OPENZIM_MCP_CACHE__MAX_SIZE	100	最大緩存條目數
OPENZIM_MCP_CACHE__TTL_SECONDS	3600	緩存的 TTL（秒）
OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH	100000	最大內容長度
OPENZIM_MCP_CONTENT__SNIPPET_LENGTH	1000	最大片段長度
OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT	10	默認搜索結果限制
OPENZIM_MCP_LOGGING__LEVEL	INFO	日誌級別
OPENZIM_MCP_LOGGING__FORMAT	%(asctime)s - %(name)s - %(levelname)s - %(message)s	日誌消息格式
OPENZIM_MCP_SERVER_NAME	openzim-mcp	服務器實例名稱

🔒 安全特性

• 路徑遍歷保護：安全的路徑驗證可防止訪問允許目錄之外的內容。
• 輸入清理：所有用戶輸入都經過驗證和清理。
• 資源管理：正確清理 ZIM 存檔資源。
• 錯誤處理：清理後的錯誤消息可防止信息洩露。
• 類型安全：完整的類型註解可防止與類型相關的漏洞。

🚀 性能特性

• 智能緩存：具有 TTL 的 LRU 緩存，用於頻繁訪問的內容。
• 資源池化：高效的 ZIM 存檔管理。
• 優化的內容處理：快速的 HTML 到文本轉換。
• 懶加載：僅在需要時初始化組件。
• 內存管理：正確的清理和資源管理。

🧪 測試

該項目包括全面的測試，覆蓋率超過 90%，使用了模擬數據和真實的 ZIM 文件：

測試類別

• 單元測試：使用模擬數據對單個組件進行測試。
• 集成測試：使用真實的 ZIM 文件進行端到端功能測試。
• 安全測試：進行路徑遍歷和輸入驗證測試。
• 性能測試：進行緩存和資源管理測試。
• 格式兼容性：測試各種 ZIM 文件格式和版本。
• 錯誤處理：使用無效和格式錯誤的 ZIM 文件進行測試。

測試基礎設施

OpenZIM MCP 使用混合測試方法：

1. 基於模擬的測試：使用模擬的 libzim 組件進行快速單元測試。
2. 真實 ZIM 文件測試：使用官方的 zim-testing-suite 文件進行集成測試。
3. 自動測試數據管理：根據需要下載和組織測試文件。

測試數據來源

• 內置測試數據：倉庫中包含的基本測試文件。
• zim-testing-suite 集成：來自 OpenZIM 項目的官方測試文件。
• 環境變量支持：使用 ZIM_TEST_DATA_DIR 指定自定義測試數據位置。

# 運行帶覆蓋率報告的測試
make test-cov

# 查看覆蓋率報告
open htmlcov/index.html

# 使用真實的 ZIM 文件運行全面測試
make test-with-zim-data

測試標記

測試使用 pytest 標記進行組織：

• @pytest.mark.requires_zim_data：需要 ZIM 測試數據文件的測試。
• @pytest.mark.integration：集成測試。
• @pytest.mark.slow：長時間運行的測試。

📈 監控

OpenZIM MCP 提供內置的監控功能：

• 健康檢查：監控服務器的健康狀況和狀態。
• 緩存指標：緩存命中率和性能統計信息。
• 結構化日誌：JSON 格式的日誌，便於解析。
• 錯誤跟蹤：全面的錯誤日誌記錄和跟蹤。

🔄 版本管理

本項目使用 語義化版本控制，並通過 release-please 進行自動版本管理。

自動發佈

版本升級和發佈基於 Conventional Commits 自動進行：

• feat: - 新特性（次版本升級）
• fix: - 錯誤修復（補丁版本升級）
• feat!: 或 BREAKING CHANGE: - 重大變更（主版本升級）
• perf: - 性能改進（補丁版本升級）
• docs:、style:、refactor:、test:、chore: - 不進行版本升級

發佈流程

該項目使用一個 改進的、統一的發佈系統，並進行自動驗證：

1. 自動（推薦）：推送符合規範的提交 → Release Please 創建 PR → 合併 PR → 自動發佈
2. 手動：使用 GitHub Actions UI 直接控制發佈
3. 緊急情況：直接推送標籤以進行關鍵修復

關鍵特性：

• ✅ 主分支的零接觸發布
• ✅ 自動版本同步驗證
• ✅ 每次發佈前的全面測試
• ✅ 改進的錯誤處理和回滾能力
• ✅ 分支保護 防止發佈失敗

詳細說明請參閱 發佈流程指南。

提交消息格式

<類型>[可選範圍]: <描述>

[可選正文]

[可選腳註]

示例：

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 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• Kiwix 提供 ZIM 格式和 libzim 庫。
• MCP 提供模型上下文協議。
• 開源社區提供了本項目中使用的優秀庫。