Openzim MCP

🚀 OpenZIM MCP Server

OpenZIM MCPは、静的なZIMアーカイブを大規模言語モデル（LLM）用の動的な知識エンジンに変換するツールです。基本的なファイルリーダーとは異なり、このツールはLLMが膨大な知識リポジトリを効果的にナビゲートし理解するために必要な、インテリジェントで構造化されたアクセスを提供します。

🚀 クイックスタート

インストール

# PyPIからインストール（推奨）
pip install openzim-mcp

開発用インストール

貢献者や開発者向けです。

# リポジトリをクローン
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# 依存関係をインストール
uv sync

# 開発用依存関係をインストール
uv sync --dev

ZIMファイルの準備

Kiwix LibraryからZIMファイル（例：Wikipedia、Wiktionaryなど）をダウンロードし、ディレクトリに配置します。

mkdir ~/zim-files
# ZIMファイルを~/zim-files/にダウンロード

サーバーの起動

# コンソールスクリプトを使用する場合（pip install後）
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"
    ]
  }
}

✨ 主な機能

• 🔒 セキュリティ第一：包括的な入力検証とパストラバーサル保護
• ⚡ 高パフォーマンス：インテリジェントなキャッシュと最適化されたZIMファイル操作
• 🧠 スマートな検索：直接アクセスから検索ベースの検索への自動フォールバックにより、信頼性の高いエントリアクセス
• 🧪 十分にテスト済み：包括的なテストスイートにより90%以上のテストカバレッジ
• 🏗️ モダンなアーキテクチャ：依存性注入を用いたモジュール化設計
• 📝 型安全：コードベース全体に完全な型注釈
• 🔧 設定可能：検証付きの柔軟な設定
• 📊 監視可能：構造化されたロギングとヘルスモニタリング

💻 使用例

基本的な使用法

# 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"
  }
]

高度な使用法

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

📚 ドキュメント

利用可能なツール

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ファイルのパス

返り値: エントリ数、アーカイブ情報、タイトル、説明、言語、作成者などのメタデータエントリを含むJSON文字列。

get_main_page - W名前空間からメインページのエントリを取得

必須パラメーター:

• zim_file_path (文字列): ZIMファイルのパス

返り値: メインページのコンテンツまたはメインページエントリに関する情報。

list_namespaces - 利用可能な名前空間とそのエントリ数を一覧表示

必須パラメーター:

• zim_file_path (文字列): ZIMファイルのパス

返り値: 各名前空間（C、M、W、Xなど）のエントリ数、説明、サンプルエントリを含む名前空間情報のJSON文字列。

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文字列。

get_server_health - サーバーのヘルスと統計情報を取得

パラメーターは必要ありません。

返り値:

• サーバーの状態とパフォーマンスメトリクス
• キャッシュ統計情報
• 設定情報
• インスタンス追跡情報
• 競合検出結果

get_server_configuration - 詳細なサーバー設定を取得

パラメーターは必要ありません。

返り値: 診断情報、検証結果、競合検出を含む包括的なサーバー設定。

diagnose_server_state - 包括的なサーバー診断

パラメーターは必要ありません。

返り値: インスタンスの競合、設定の検証、ファイルのアクセシビリティチェック、および実行可能な推奨事項を含む詳細な診断情報。

resolve_server_conflicts - サーバーの競合を特定して解決

パラメーターは必要ありません。

返り値: クリーンアップアクションと推奨事項を含む競合解決の結果。

🔧 技術詳細

ZIMエントリ検索のベストプラクティス

スマートな検索システム

OpenZIM MCPは、ZIMファイルで一般的なパスエンコーディングの不一致を自動的に処理するインテリジェントなエントリ検索システムを実装しています。

動作原理:

1. まず直接アクセス: 提供されたパスをそのまま使用してエントリを取得しようとします。
2. 自動フォールバック: 直接アクセスが失敗した場合、さまざまな検索用語を使用してエントリを自動的に検索します。
3. パスマッピングキャッシュ: 成功したパスマッピングをキャッシュして、繰り返しのアクセス時のパフォーマンスを向上させます。
4. 強化されたエラーガイダンス: エントリが見つからない場合に明確なガイダンスを提供します。

LLMユーザーにとっての利点:

• 透過的な操作: 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"
  }
}

エントリが見つからない場合

システムは自動的にガイダンスを提供します。

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.

マルチサーバーインスタンス管理

OpenZIM MCPには、複数のサーバーインスタンスが実行されている場合の信頼性の高い動作を保証するための高度なマルチサーバーインスタンス追跡と競合検出が含まれています。

インスタンス追跡機能

• 自動インスタンス登録: 各サーバーインスタンスは、一意のプロセスIDと設定ハッシュで自動的に登録されます。
• 競合検出: 異なる設定の複数のサーバーが同じディレクトリにアクセスしていることを検出します。
• 古いインスタンスのクリーンアップ: 終了したプロセスからの孤立したインスタンスファイルを自動的に識別してクリーンアップします。
• 設定検証: すべてのサーバーインスタンスが互換性のある設定を使用することを保証します。

競合の種類

1. 設定の不一致: 異なる設定の複数のサーバーが同じディレクトリにアクセスしている場合。
2. 複数のインスタンス: 複数のサーバーが同時に実行されている場合（混乱を引き起こす可能性があります）。
3. 古いインスタンス: 終了したプロセスからの孤立したインスタンスファイル。

自動競合警告

OpenZIM MCPは、問題が検出された場合、検索結果やファイルリストに自動的に競合警告を含めます。

🔍 **Server Conflict Detected**
⚠️ Configuration mismatch with server PID 12345. Search results may be inconsistent.
💡 Use 'resolve_server_conflicts()' to fix these issues.

ベストプラクティス

• 定期的に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からテキストへの変換
• 遅延ローディング: 必要なときにのみコンポーネントが初期化されます
• メモリ管理: 適切なクリーンアップとリソース管理

テスト

このプロジェクトには、モックデータと実際のZIMファイルの両方を使用した包括的なテストが含まれており、90%以上のカバレッジがあります。

テストのカテゴリ

• 単体テスト: モックを使用した個々のコンポーネントのテスト
• 統合テスト: 実際の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形式のログ
• エラー追跡: 包括的なエラーロギングと追跡

バージョニング

このプロジェクトはSemantic Versioningを使用しており、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. 緊急: 重要な修正のために直接タグをプッシュ

主要な機能:

• ✅ メインブランチからのゼロタッチリリース
• ✅ 自動バージョン同期の検証
• ✅ リリース前の包括的なテスト
• ✅ 改善されたエラーハンドリングとロールバック機能
• ✅ ブランチ保護による破損したリリースの防止

詳細な手順については、Release Process Guideを参照してください。

コミットメッセージのフォーマット

<type>[optional scope]: <description>

[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ライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• KiwixのZIMフォーマットとlibzimライブラリ
• MCPのModel Context Protocol
• このプロジェクトで使用されている優れたライブラリを提供しているオープンソースコミュニティ