OpenZIM MCP Server

1<p align="center">
2  <img src="https://raw.githubusercontent.com/cameronrye/openzim-mcp/main/website/assets/logo.svg" alt="OpenZIM MCP Logo" width="120" height="120">
3</p>
4 
5<h1 align="center">OpenZIM MCP Server</h1>
6 
7<p align="center">
8  <strong>Transform static ZIM archives into dynamic knowledge engines for AI models</strong>
9</p>
10 
11<p align="center">
12  <a href="https://github.com/cameronrye/openzim-mcp/actions/workflows/test.yml"><img src="https://github.com/cameronrye/openzim-mcp/workflows/CI/badge.svg" alt="CI"></a>
13  <a href="https://codecov.io/gh/cameronrye/openzim-mcp"><img src="https://codecov.io/gh/cameronrye/openzim-mcp/branch/main/graph/badge.svg" alt="codecov"></a>
14  <a href="https://github.com/cameronrye/openzim-mcp/actions/workflows/codeql.yml"><img src="https://github.com/cameronrye/openzim-mcp/workflows/CodeQL%20Security%20Analysis/badge.svg" alt="CodeQL"></a>
15  <a href="https://sonarcloud.io/summary/new_code?id=cameronrye_openzim-mcp"><img src="https://sonarcloud.io/api/project_badges/measure?project=cameronrye_openzim-mcp&metric=security_rating" alt="Security Rating"></a>
16</p>
17 
18<p align="center">
19  <a href="https://badge.fury.io/py/openzim-mcp"><img src="https://badge.fury.io/py/openzim-mcp.svg" alt="PyPI version"></a>
20  <a href="https://pypi.org/project/openzim-mcp/"><img src="https://img.shields.io/pypi/pyversions/openzim-mcp" alt="PyPI - Python Version"></a>
21  <a href="https://pypi.org/project/openzim-mcp/"><img src="https://img.shields.io/pypi/dm/openzim-mcp" alt="PyPI - Downloads"></a>
22  <a href="https://github.com/cameronrye/openzim-mcp/releases"><img src="https://img.shields.io/github/v/release/cameronrye/openzim-mcp" alt="GitHub release"></a>
23</p>
24 
25<p align="center">
26  <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
27  <a href="https://pycqa.github.io/isort/"><img src="https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336" alt="Imports: isort"></a>
28  <a href="https://mypy-lang.org/"><img src="https://img.shields.io/badge/type%20checked-mypy-blue" alt="Type checked: mypy"></a>
29  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
30</p>
31 
32<p align="center">
33  <a href="https://github.com/cameronrye/openzim-mcp/issues"><img src="https://img.shields.io/github/issues/cameronrye/openzim-mcp" alt="GitHub issues"></a>
34  <a href="https://github.com/cameronrye/openzim-mcp/pulls"><img src="https://img.shields.io/github/issues-pr/cameronrye/openzim-mcp" alt="GitHub pull requests"></a>
35  <a href="https://github.com/cameronrye/openzim-mcp/graphs/contributors"><img src="https://img.shields.io/github/contributors/cameronrye/openzim-mcp" alt="GitHub contributors"></a>
36  <a href="https://github.com/cameronrye/openzim-mcp/stargazers"><img src="https://img.shields.io/github/stars/cameronrye/openzim-mcp?style=social" alt="GitHub stars"></a>
37</p>
38 
39---
40 
41> 🆕 **NEW: Article Summaries & Table of Contents!** Extract concise article summaries and hierarchical table of contents for quick content overview. Plus pagination cursors for seamless navigation! [Learn more →](#get_entry_summary---get-a-concise-article-summary)
42 
43> **Dual Mode Support:** Choose between Simple mode (1 intelligent natural language tool, default) or Advanced mode (18 specialized tools) to match your LLM's capabilities.
44 
45## Built for LLM Intelligence
46 
47**OpenZIM MCP transforms static ZIM archives into dynamic knowledge engines for Large Language Models.** Unlike basic file readers, this tool provides *intelligent, structured access* that LLMs need to effectively navigate and understand vast knowledge repositories.
48 
49 **Why LLMs Love OpenZIM MCP:**
50 
51- **Smart Navigation**: Browse by namespace (articles, metadata, media) instead of blind searching
52- **Context-Aware Discovery**: Get article structure, relationships, and metadata for deeper understanding
53- **Intelligent Search**: Advanced filtering, auto-complete suggestions, and relevance-ranked results
54- **Performance Optimized**: Cached operations and pagination prevent timeouts on massive archives
55- **Relationship Mapping**: Extract internal/external links to understand content connections
56 
57Whether you're building a research assistant, knowledge chatbot, or content analysis system, OpenZIM MCP gives your LLM the structured access patterns it needs to unlock the full potential of offline knowledge archives. No more fumbling through raw text dumps!
58 
59**OpenZIM MCP** is a modern, secure, and high-performance MCP (Model Context Protocol) server that enables AI models to access and search [ZIM format](https://en.wikipedia.org/wiki/ZIM_(file_format)) knowledge bases offline.
60 
61[ZIM](https://en.wikipedia.org/wiki/ZIM_(file_format)) (Zeno IMproved) is an open file format developed by the [openZIM project](https://openzim.org/), designed specifically for offline storage and access to website content. The format supports high compression rates using Zstandard compression (default since 2021) and enables fast full-text searching, making it ideal for storing entire Wikipedia content and other large reference materials in relatively compact files. The openZIM project is sponsored by Wikimedia CH and supported by the Wikimedia Foundation, ensuring the format's continued development and adoption for offline knowledge access, especially in environments without reliable internet connectivity.
62 
63## Features
64 
65- **Dual Mode Support**: Choose between Simple mode (1 intelligent natural language tool, default) or Advanced mode (18 specialized tools)
66- **Binary Content Retrieval**: 🆕 Extract PDFs, images, videos, and other embedded media for multi-agent workflows
67- **Security First**: Comprehensive input validation and path traversal protection
68- **High Performance**: Intelligent caching and optimized ZIM file operations
69- **Smart Retrieval**: Automatic fallback from direct access to search-based retrieval for reliable entry access
70- **Well Tested**: 80%+ test coverage with comprehensive test suite
71- **Modern Architecture**: Modular design with dependency injection
72- **Type Safe**: Full type annotations throughout the codebase
73- **Configurable**: Flexible configuration with validation
74- **Observable**: Structured logging and health monitoring
75 
76## Quick Start
77 
78### Installation
79 
80```bash
81# Install from PyPI (recommended)
82pip install openzim-mcp
83```
84 
85### Development Installation
86 
87For contributors and developers:
88 
89```bash
90# Clone the repository
91git clone https://github.com/cameronrye/openzim-mcp.git
92cd openzim-mcp
93 
94# Install dependencies
95uv sync
96 
97# Install development dependencies
98uv sync --dev
99```
100 
101### Prepare ZIM Files
102 
103Download ZIM files (e.g., Wikipedia, Wiktionary, etc.) from the [Kiwix Library](https://browse.library.kiwix.org/) and place them in a directory:
104 
105```bash
106mkdir ~/zim-files
107# Download ZIM files to ~/zim-files/
108```
109 
110### Running the Server
111 
112```bash
113# Simple mode (default) - 1 intelligent natural language tool
114openzim-mcp /path/to/zim/files
115python -m openzim_mcp /path/to/zim/files
116 
117# Advanced mode - all 18 specialized tools
118openzim-mcp --mode advanced /path/to/zim/files
119python -m openzim_mcp --mode advanced /path/to/zim/files
120 
121# For development (from source)
122uv run python -m openzim_mcp /path/to/zim/files
123uv run python -m openzim_mcp --mode advanced /path/to/zim/files
124 
125# Or using make (development)
126make run ZIM_DIR=/path/to/zim/files
127```
128 
129### Tool Modes
130 
131OpenZIM MCP supports two modes:
132 
133- **Simple Mode** (default): Provides 1 intelligent tool (`zim_query`) that accepts natural language queries
134- **Advanced Mode**: Exposes all 18 specialized MCP tools for maximum control
135 
136See [Simple Mode Guide](docs/SIMPLE_MODE_GUIDE.md) for detailed information.
137 
138### MCP Configuration
139 
140**Simple Mode (default):**
141 
142```json
143{
144  "openzim-mcp": {
145    "command": "openzim-mcp",
146    "args": ["/path/to/zim/files"]
147  }
148}
149```
150 
151**Advanced Mode:**
152 
153```json
154{
155  "openzim-mcp-advanced": {
156    "command": "openzim-mcp",
157    "args": ["--mode", "advanced", "/path/to/zim/files"]
158  }
159}
160```
161 
162Alternative configuration using Python module:
163 
164```json
165{
166  "openzim-mcp": {
167    "command": "python",
168    "args": [
169      "-m",
170      "openzim_mcp",
171      "/path/to/zim/files"
172    ]
173  }
174}
175```
176 
177For development (from source):
178 
179```json
180{
181  "openzim-mcp": {
182    "command": "uv",
183    "args": [
184      "--directory",
185      "/path/to/openzim-mcp",
186      "run",
187      "python",
188      "-m",
189      "openzim_mcp",
190      "/path/to/zim/files"
191    ]
192  }
193}
194```
195 
196## Development
197 
198### Running Tests
199 
200```bash
201# Run all tests
202make test
203 
204# Run tests with coverage
205make test-cov
206 
207# Run specific test file
208uv run pytest tests/test_security.py -v
209 
210# Run tests with ZIM test data (comprehensive testing)
211make test-with-zim-data
212 
213# Run integration tests only
214make test-integration
215 
216# Run tests that require ZIM test data
217make test-requires-zim-data
218```
219 
220### ZIM Test Data Integration
221 
222OpenZIM MCP integrates with the official [zim-testing-suite](https://github.com/openzim/zim-testing-suite) for comprehensive testing with real ZIM files:
223 
224```bash
225# Download essential test files (basic testing)
226make download-test-data
227 
228# Download all test files (comprehensive testing)
229make download-test-data-all
230 
231# List available test files
232make list-test-data
233 
234# Clean downloaded test data
235make clean-test-data
236```
237 
238The test data includes:
239 
240- **Basic files**: Small ZIM files for essential testing
241- **Real content**: Actual Wikipedia/Wikibooks content for integration testing
242- **Invalid files**: Malformed ZIM files for error handling testing
243- **Special cases**: Embedded content, split files, and edge cases
244 
245Test files are automatically organized by category and priority level.
246 
247### Code Quality
248 
249```bash
250# Format code
251make format
252 
253# Run linting
254make lint
255 
256# Type checking
257make type-check
258 
259# Run all checks
260make check
261```
262 
263### Project Structure
264 
265```text
266openzim-mcp/
267├── openzim_mcp/             # Main package
268│   ├── __init__.py        # Package initialization
269│   ├── __main__.py        # Module entry point
270│   ├── main.py            # Main entry point
271│   ├── server.py          # MCP server implementation
272│   ├── config.py          # Configuration management
273│   ├── security.py        # Security and validation
274│   ├── cache.py           # Caching functionality
275│   ├── content_processor.py # Content processing
276│   ├── zim_operations.py  # ZIM file operations
277│   ├── exceptions.py      # Custom exceptions
278│   └── constants.py       # Application constants
279├── tests/                 # Test suite
280├── pyproject.toml        # Project configuration
281├── Makefile              # Development commands
282└── README.md             # This file
283```
284 
285---
286 
287## API Reference
288 
289### Available Tools
290 
291### list_zim_files - List all ZIM files in allowed directories
292 
293No parameters required.
294 
295### search_zim_file - Search within ZIM file content
296 
297**Required parameters:**
298 
299- `zim_file_path` (string): Path to the ZIM file
300- `query` (string): Search query term
301 
302**Optional parameters:**
303 
304- `limit` (integer, default: 10): Maximum number of results to return
305- `offset` (integer, default: 0): Starting offset for results (for pagination)
306 
307### get_zim_entry - Get detailed content of a specific entry in a ZIM file
308 
309**Required parameters:**
310 
311- `zim_file_path` (string): Path to the ZIM file
312- `entry_path` (string): Entry path, e.g., 'A/Some_Article'
313 
314**Optional parameters:**
315 
316- `max_content_length` (integer, default: 100000, minimum: 1000): Maximum length of returned content
317 
318**Smart Retrieval Features:**
319 
320- **Automatic Fallback**: If direct path access fails, automatically searches for the entry and uses the exact path found
321- **Path Mapping Cache**: Caches successful path mappings for improved performance on repeated access
322- **Enhanced Error Guidance**: Provides clear guidance when entries cannot be found, suggesting alternative approaches
323- **Transparent Operation**: Works seamlessly regardless of path encoding differences (spaces vs underscores, URL encoding, etc.)
324 
325### get_zim_metadata - Get ZIM file metadata from M namespace entries
326 
327**Required parameters:**
328 
329- `zim_file_path` (string): Path to the ZIM file
330 
331**Returns:**
332JSON string containing ZIM metadata including entry counts, archive information, and metadata entries like title, description, language, creator, etc.
333 
334### get_main_page - Get the main page entry from W namespace
335 
336**Required parameters:**
337 
338- `zim_file_path` (string): Path to the ZIM file
339 
340**Returns:**
341Main page content or information about the main page entry.
342 
343### list_namespaces - List available namespaces and their entry counts
344 
345**Required parameters:**
346 
347- `zim_file_path` (string): Path to the ZIM file
348 
349**Returns:**
350JSON string containing namespace information with entry counts, descriptions, and sample entries for each namespace (C, M, W, X, etc.).
351 
352### browse_namespace - Browse entries in a specific namespace with pagination
353 
354**Required parameters:**
355 
356- `zim_file_path` (string): Path to the ZIM file
357- `namespace` (string): Namespace to browse (C, M, W, X, A, I, etc.)
358 
359**Optional parameters:**
360 
361- `limit` (integer, default: 50, range: 1-200): Maximum number of entries to return
362- `offset` (integer, default: 0): Starting offset for pagination
363 
364**Returns:**
365JSON string containing namespace entries with titles, content previews, and pagination information.
366 
367### search_with_filters - Search within ZIM file content with advanced filters
368 
369**Required parameters:**
370 
371- `zim_file_path` (string): Path to the ZIM file
372- `query` (string): Search query term
373 
374**Optional parameters:**
375 
376- `namespace` (string): Optional namespace filter (C, M, W, X, etc.)
377- `content_type` (string): Optional content type filter (text/html, text/plain, etc.)
378- `limit` (integer, default: 10, range: 1-100): Maximum number of results to return
379- `offset` (integer, default: 0): Starting offset for pagination
380 
381**Returns:**
382Filtered search results with namespace and content type information.
383 
384### get_search_suggestions - Get search suggestions and auto-complete
385 
386**Required parameters:**
387 
388- `zim_file_path` (string): Path to the ZIM file
389- `partial_query` (string): Partial search query (minimum 2 characters)
390 
391**Optional parameters:**
392 
393- `limit` (integer, default: 10, range: 1-50): Maximum number of suggestions to return
394 
395**Returns:**
396JSON string containing search suggestions based on article titles and content.
397 
398### get_article_structure - Extract article structure and metadata
399 
400**Required parameters:**
401 
402- `zim_file_path` (string): Path to the ZIM file
403- `entry_path` (string): Entry path, e.g., 'C/Some_Article'
404 
405**Returns:**
406JSON string containing article structure including headings, sections, metadata, and word count.
407 
408### extract_article_links - Extract internal and external links from an article
409 
410**Required parameters:**
411 
412- `zim_file_path` (string): Path to the ZIM file
413- `entry_path` (string): Entry path, e.g., 'C/Some_Article'
414 
415**Returns:**
416JSON string containing categorized links (internal, external, media) with titles and metadata.
417 
418### get_entry_summary - Get a concise article summary
419 
420**Required parameters:**
421 
422- `zim_file_path` (string): Path to the ZIM file
423- `entry_path` (string): Entry path, e.g., 'C/Some_Article'
424 
425**Optional parameters:**
426 
427- `max_words` (integer, default: 200, range: 10-1000): Maximum number of words in the summary
428 
429**Returns:**
430JSON string containing a concise summary extracted from the article's opening paragraphs, with metadata including title, word count, and truncation status.
431 
432**Features:**
433 
434- Extracts opening paragraphs while removing infoboxes, navigation, and sidebars
435- Provides quick article overview without loading full content
436- Useful for LLMs to understand article context before deciding to read more
437 
438### get_table_of_contents - Extract hierarchical table of contents
439 
440**Required parameters:**
441 
442- `zim_file_path` (string): Path to the ZIM file
443- `entry_path` (string): Entry path, e.g., 'C/Some_Article'
444 
445**Returns:**
446JSON string containing a hierarchical tree structure of article headings (h1-h6), suitable for navigation and content overview.
447 
448**Features:**
449 
450- Hierarchical tree structure with nested children
451- Includes heading levels, text, and anchor IDs
452- Provides heading count and maximum depth statistics
453- Enables LLMs to navigate directly to specific sections
454 
455### get_binary_entry - Retrieve binary content from a ZIM entry
456 
457**Required parameters:**
458 
459- `zim_file_path` (string): Path to the ZIM file
460- `entry_path` (string): Entry path, e.g., 'I/image.png' or 'I/document.pdf'
461 
462**Optional parameters:**
463 
464- `max_size_bytes` (integer): Maximum size of content to return (default: 10MB). Content larger than this will return metadata only.
465- `include_data` (boolean): If true (default), include base64-encoded data. Set to false to retrieve metadata only.
466 
467**Returns:**
468 
469JSON string containing:
470 
471- `path`: Entry path in ZIM file
472- `title`: Entry title
473- `mime_type`: Content type (e.g., "application/pdf", "image/png")
474- `size`: Size in bytes
475- `size_human`: Human-readable size (e.g., "1.5 MB")
476- `encoding`: "base64" when data is included, null otherwise
477- `data`: Base64-encoded content (if include_data=true and under size limit)
478- `truncated`: Boolean indicating if content exceeded size limit
479 
480**Use Cases:**
481 
482- Retrieve PDFs for processing with PDF parsing tools
483- Extract images for vision models or OCR tools
484- Get video/audio files for transcription services
485- Enable multi-agent workflows with specialized content processors
486 
487---
488 
489## Examples
490 
491### Listing ZIM files
492 
493```json
494{
495  "name": "list_zim_files"
496}
497```
498 
499Response:
500 
501```plain
502Found 1 ZIM files in 1 directories:
503 
504[
505  {
506    "name": "wikipedia_en_100_2025-08.zim",
507    "path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
508    "directory": "C:\\zim",
509    "size": "310.77 MB",
510    "modified": "2025-09-11T10:20:50.148427"
511  }
512]
513```
514 
515### Searching ZIM files
516 
517```json
518{
519  "name": "search_zim_file",
520  "arguments": {
521    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
522    "query": "biology",
523    "limit": 3
524  }
525}
526```
527 
528Response:
529 
530```plain
531Found 51 matches for "biology", showing 1-3:
532 
533## 1. Taxonomy (biology)
534Path: Taxonomy_(biology)
535Snippet: #  Taxonomy (biology) Part of a series on
536---
537Evolutionary biology
538Darwin's finches by John Gould
539 
540  * Index
541  * Introduction
542  * [Main](Evolution "Evolution")
543  * Outline
544 
545## 2. Protein
546Path: Protein
547Snippet: #  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).
548 
549## 3. Ant
550Path: Ant
551Snippet: #  Ant Ants
552Temporal range: Late Aptian – Present
553---
554Fire ants
555[Scientific classification](Taxonomy_\(biology\) "Taxonomy \(biology\)")
556Kingdom:  | [Animalia](Animal "Animal")
557Phylum:  | [Arthropoda](Arthropod "Arthropod")
558Class:  | [Insecta](Insect "Insect")
559Order:  | Hymenoptera
560Infraorder:  | Aculeata
561Superfamily:  |
562Latreille, 1809[1]
563Family:  |
564Latreille, 1809
565```
566 
567### Getting ZIM entries
568 
569```json
570{
571  "name": "get_zim_entry",
572  "arguments": {
573    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
574    "entry_path": "Protein"
575  }
576}
577```
578 
579Response:
580 
581```plain
582# Protein
583 
584Path: Protein
585Type: text/html
586## Content
587 
588#  Protein
589 
590A 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).
591 
592**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.
593 
594A 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.
595 
596... [Content truncated, total of 56,202 characters, only showing first 1,500 characters] ...
597```
598 
599### Smart Retrieval in Action
600 
601**Example: Automatic path resolution**
602 
603```json
604{
605  "name": "get_zim_entry",
606  "arguments": {
607    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
608    "entry_path": "A/Test Article"
609  }
610}
611```
612 
613Response (showing smart retrieval working):
614 
615```plain
616# Test Article
617 
618Requested Path: A/Test Article
619Actual Path: A/Test_Article
620Type: text/html
621 
622## Content
623 
624# Test Article
625 
626This article demonstrates the smart retrieval system automatically handling
627path encoding differences. The system tried "A/Test Article" directly,
628then automatically searched and found "A/Test_Article".
629 
630... [Content continues] ...
631```
632 
633### get_server_health - Get server health and statistics
634 
635No parameters required.
636 
637**Returns:**
638 
639- Server status and performance metrics
640- Cache statistics
641- Configuration information
642- Instance tracking information
643- Conflict detection results
644 
645**Example Response:**
646 
647```json
648{
649  "status": "healthy",
650  "server_name": "openzim-mcp",
651  "allowed_directories": 1,
652  "cache": {
653    "enabled": true,
654    "size": 1,
655    "max_size": 100,
656    "ttl_seconds": 3600
657  },
658  "instance_tracking": {
659    "active_instances": 1,
660    "conflicts_detected": 0
661  }
662}
663```
664 
665### get_server_configuration - Get detailed server configuration
666 
667No parameters required.
668 
669**Returns:**
670Comprehensive server configuration including diagnostics, validation results, and conflict detection.
671 
672**Example Response:**
673 
674```json
675{
676  "configuration": {
677    "server_name": "openzim-mcp",
678    "allowed_directories": ["/path/to/zim/files"],
679    "cache_enabled": true,
680    "config_hash": "abc123...",
681    "server_pid": 12345
682  },
683  "diagnostics": {
684    "validation_status": "healthy",
685    "conflicts_detected": [],
686    "warnings": [],
687    "recommendations": []
688  }
689}
690```
691 
692### diagnose_server_state - Comprehensive server diagnostics
693 
694No parameters required.
695 
696**Returns:**
697Detailed diagnostic information including instance conflicts, configuration validation, file accessibility checks, and actionable recommendations.
698 
699**Example Response:**
700 
701```json
702{
703  "status": "healthy",
704  "server_info": {
705    "pid": 12345,
706    "server_name": "openzim-mcp",
707    "config_hash": "abc123..."
708  },
709  "conflicts": [],
710  "issues": [],
711  "recommendations": ["Server appears to be running normally"],
712  "environment_checks": {
713    "directories_accessible": true,
714    "cache_functional": true
715  }
716}
717```
718 
719### resolve_server_conflicts - Identify and resolve server conflicts
720 
721No parameters required.
722 
723**Returns:**
724Results of conflict resolution including cleanup actions and recommendations.
725 
726**Example Response:**
727 
728```json
729{
730  "status": "success",
731  "cleanup_results": {
732    "stale_instances_removed": 2
733  },
734  "conflicts_found": [],
735  "actions_taken": ["Removed 2 stale instance files"],
736  "recommendations": ["No active conflicts detected"]
737}
738```
739 
740### Additional Search Examples
741 
742**Computer-related search:**
743 
744```json
745{
746  "name": "search_zim_file",
747  "arguments": {
748    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
749    "query": "computer",
750    "limit": 2
751  }
752}
753```
754 
755Response:
756 
757```plain
758Found 39 matches for "computer", showing 1-2:
759 
760## 1. Video game
761Path: Video_game
762Snippet: #  Video game First-generation _Pong_ console at the Computerspielemuseum Berlin
763---
764Platforms
765 
766## 2. Protein
767Path: Protein
768Snippet: #  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).
769```
770 
771**Getting detailed content:**
772 
773```json
774{
775  "name": "get_zim_entry",
776  "arguments": {
777    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
778    "entry_path": "Evolution",
779    "max_content_length": 1500
780  }
781}
782```
783 
784Response:
785 
786```plain
787# Evolution
788 
789Path: Evolution
790Type: text/html
791## Content
792 
793#  Evolution
794 
795Part of the Biology series on
796---
797****
798Mechanisms and processes
799 
800  * Adaptation
801  * Genetic drift
802  * Gene flow
803  * History of life
804  * Maladaptation
805  * Mutation
806  * Natural selection
807  * Neutral theory
808  * Population genetics
809  * Speciation
810 
811... [Content truncated, total of 110,237 characters, only showing first 1,500 characters] ...
812```
813 
814### Advanced Knowledge Retrieval Examples
815 
816**Getting ZIM metadata:**
817 
818```json
819{
820  "name": "get_zim_metadata",
821  "arguments": {
822    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim"
823  }
824}
825```
826 
827Response:
828 
829```json
830{
831  "entry_count": 100000,
832  "all_entry_count": 120000,
833  "article_count": 80000,
834  "media_count": 20000,
835  "metadata_entries": {
836    "Title": "Wikipedia (English)",
837    "Description": "Wikipedia articles in English",
838    "Language": "eng",
839    "Creator": "Kiwix",
840    "Date": "2025-08-15"
841  }
842}
843```
844 
845**Browsing a namespace:**
846 
847```json
848{
849  "name": "browse_namespace",
850  "arguments": {
851    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
852    "namespace": "C",
853    "limit": 5,
854    "offset": 0
855  }
856}
857```
858 
859Response:
860 
861```json
862{
863  "namespace": "C",
864  "total_in_namespace": 80000,
865  "offset": 0,
866  "limit": 5,
867  "returned_count": 5,
868  "has_more": true,
869  "entries": [
870    {
871      "path": "C/Biology",
872      "title": "Biology",
873      "content_type": "text/html",
874      "preview": "Biology is the scientific study of life..."
875    }
876  ]
877}
878```
879 
880**Filtered search:**
881 
882```json
883{
884  "name": "search_with_filters",
885  "arguments": {
886    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
887    "query": "evolution",
888    "namespace": "C",
889    "content_type": "text/html",
890    "limit": 3
891  }
892}
893```
894 
895**Getting article structure:**
896 
897```json
898{
899  "name": "get_article_structure",
900  "arguments": {
901    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
902    "entry_path": "C/Evolution"
903  }
904}
905```
906 
907Response:
908 
909```json
910{
911  "title": "Evolution",
912  "path": "C/Evolution",
913  "content_type": "text/html",
914  "headings": [
915    {"level": 1, "text": "Evolution", "id": "evolution"},
916    {"level": 2, "text": "History", "id": "history"},
917    {"level": 2, "text": "Mechanisms", "id": "mechanisms"}
918  ],
919  "sections": [
920    {
921      "title": "Evolution",
922      "level": 1,
923      "content_preview": "Evolution is the change in heritable traits...",
924      "word_count": 150
925    }
926  ],
927  "word_count": 5000
928}
929```
930 
931**Getting article summary:**
932 
933```json
934{
935  "name": "get_entry_summary",
936  "arguments": {
937    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
938    "entry_path": "C/Evolution",
939    "max_words": 100
940  }
941}
942```
943 
944Response:
945 
946```json
947{
948  "title": "Evolution",
949  "path": "C/Evolution",
950  "content_type": "text/html",
951  "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...",
952  "word_count": 100,
953  "is_truncated": true
954}
955```
956 
957**Getting table of contents:**
958 
959```json
960{
961  "name": "get_table_of_contents",
962  "arguments": {
963    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
964    "entry_path": "C/Evolution"
965  }
966}
967```
968 
969Response:
970 
971```json
972{
973  "title": "Evolution",
974  "path": "C/Evolution",
975  "content_type": "text/html",
976  "toc": [
977    {
978      "level": 1,
979      "text": "Evolution",
980      "id": "evolution",
981      "children": [
982        {
983          "level": 2,
984          "text": "History of evolutionary thought",
985          "id": "history",
986          "children": []
987        },
988        {
989          "level": 2,
990          "text": "Mechanisms",
991          "id": "mechanisms",
992          "children": []
993        }
994      ]
995    }
996  ],
997  "heading_count": 15,
998  "max_depth": 4
999}
1000```
1001 
1002**Getting search suggestions:**
1003 
1004```json
1005{
1006  "name": "get_search_suggestions",
1007  "arguments": {
1008    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
1009    "partial_query": "bio",
1010    "limit": 5
1011  }
1012}
1013```
1014 
1015Response:
1016 
1017```json
1018{
1019  "partial_query": "bio",
1020  "suggestions": [
1021    {"text": "Biology", "path": "C/Biology", "type": "title_start_match"},
1022    {"text": "Biochemistry", "path": "C/Biochemistry", "type": "title_start_match"},
1023    {"text": "Biodiversity", "path": "C/Biodiversity", "type": "title_start_match"}
1024  ],
1025  "count": 3
1026}
1027```
1028 
1029### Server Management and Diagnostics Examples
1030 
1031**Getting server health:**
1032 
1033```json
1034{
1035  "name": "get_server_health"
1036}
1037```
1038 
1039Response:
1040 
1041```json
1042{
1043  "status": "healthy",
1044  "server_name": "openzim-mcp",
1045  "uptime_info": {
1046    "process_id": 12345,
1047    "started_at": "2025-09-14T10:30:00"
1048  },
1049  "cache_performance": {
1050    "enabled": true,
1051    "size": 15,
1052    "max_size": 100,
1053    "hit_rate": 0.85
1054  },
1055  "instance_tracking": {
1056    "active_instances": 1,
1057    "conflicts_detected": 0
1058  }
1059}
1060```
1061 
1062**Diagnosing server state:**
1063 
1064```json
1065{
1066  "name": "diagnose_server_state"
1067}
1068```
1069 
1070Response:
1071 
1072```json
1073{
1074  "status": "healthy",
1075  "server_info": {
1076    "pid": 12345,
1077    "server_name": "openzim-mcp",
1078    "config_hash": "abc123def456..."
1079  },
1080  "conflicts": [],
1081  "issues": [],
1082  "recommendations": ["Server appears to be running normally. No issues detected."],
1083  "environment_checks": {
1084    "directories_accessible": true,
1085    "cache_functional": true,
1086    "zim_files_found": 5
1087  }
1088}
1089```
1090 
1091**Resolving server conflicts:**
1092 
1093```json
1094{
1095  "name": "resolve_server_conflicts"
1096}
1097```
1098 
1099Response:
1100 
1101```json
1102{
1103  "status": "success",
1104  "cleanup_results": {
1105    "stale_instances_removed": 2,
1106    "files_cleaned": ["/home/user/.openzim_mcp_instances/server_99999.json"]
1107  },
1108  "conflicts_found": [],
1109  "actions_taken": ["Removed 2 stale instance files"],
1110  "recommendations": ["No active conflicts detected after cleanup"]
1111}
1112```
1113 
1114---
1115 
1116## ZIM Entry Retrieval Best Practices
1117 
1118### Smart Retrieval System
1119 
1120OpenZIM MCP implements an intelligent entry retrieval system that automatically handles path encoding inconsistencies common in ZIM files:
1121 
1122**How It Works:**
1123 
11241. **Direct Access First**: Attempts to retrieve the entry using the provided path exactly as given
11252. **Automatic Fallback**: If direct access fails, automatically searches for the entry using various search terms
11263. **Path Mapping Cache**: Caches successful path mappings to improve performance for repeated access
11274. **Enhanced Error Guidance**: Provides clear guidance when entries cannot be found
1128 
1129**Benefits for LLM Users:**
1130 
1131- **Transparent Operation**: No need to understand ZIM path encoding complexities
1132- **Single Tool Call**: Eliminates the need for manual search-first methodology
1133- **Reliable Results**: Consistent success across different path formats (spaces vs underscores, URL encoding, etc.)
1134- **Performance Optimized**: Cached mappings improve repeated access speed
1135 
1136**Example Scenarios Handled Automatically:**
1137 
1138- `A/Test Article` → `A/Test_Article` (space to underscore conversion)
1139- `C/Café` → `C/Caf%C3%A9` (URL encoding differences)
1140- `A/Some-Page` → `A/Some_Page` (hyphen to underscore conversion)
1141 
1142### Usage Recommendations
1143 
1144**For Direct Entry Access:**
1145 
1146```json
1147{
1148  "name": "get_zim_entry",
1149  "arguments": {
1150    "zim_file_path": "/path/to/file.zim",
1151    "entry_path": "A/Article_Name"
1152  }
1153}
1154```
1155 
1156**When Entry Not Found:**
1157The system will automatically provide guidance:
1158 
1159```
1160Entry not found: 'A/Article_Name'.
1161The entry path may not exist in this ZIM file.
1162Try using search_zim_file() to find available entries,
1163or browse_namespace() to explore the file structure.
1164```
1165 
1166---
1167 
1168## Important Notes and Limitations
1169 
1170### Content Length Requirements
1171 
1172- The `max_content_length` parameter for `get_zim_entry` must be at least 1000 characters
1173- Content longer than the specified limit will be truncated with a note showing the total character count
1174 
1175### Search Behavior
1176 
1177- Search results may include articles that contain the search terms in various contexts
1178- Results are ranked by relevance but may not always be directly related to the primary meaning of the search term
1179- Search snippets provide a preview of the content but may not show the exact location where the search term appears
1180 
1181### File Format Support
1182 
1183- Currently supports ZIM files (Zeno IMproved format)
1184- Tested with Wikipedia ZIM files (e.g., `wikipedia_en_100_2025-08.zim`)
1185- File paths must be properly escaped in JSON (use `\\` for Windows paths)
1186 
1187---
1188 
1189## Multi-Server Instance Management
1190 
1191OpenZIM MCP includes advanced multi-server instance tracking and conflict detection to ensure reliable operation when multiple server instances are running.
1192 
1193### Instance Tracking Features
1194 
1195- **Automatic Instance Registration**: Each server instance is automatically registered with a unique process ID and configuration hash
1196- **Conflict Detection**: Detects when multiple servers with different configurations are accessing the same directories
1197- **Stale Instance Cleanup**: Automatically identifies and cleans up orphaned instance files from terminated processes
1198- **Configuration Validation**: Ensures all server instances use compatible configurations
1199 
1200### Conflict Types
1201 
12021. **Configuration Mismatch**: Multiple servers with different settings accessing the same directories
12032. **Multiple Instances**: Multiple servers running simultaneously (may cause confusion)
12043. **Stale Instances**: Orphaned instance files from terminated processes
1205 
1206### Automatic Conflict Warnings
1207 
1208OpenZIM MCP automatically includes conflict warnings in search results and file listings when issues are detected:
1209 
1210```plain
1211 **Server Conflict Detected**
1212 Configuration mismatch with server PID 12345. Search results may be inconsistent.
1213 Use 'resolve_server_conflicts()' to fix these issues.
1214```
1215 
1216### Best Practices
1217 
1218- Use `diagnose_server_state()` regularly to check for conflicts
1219- Run `resolve_server_conflicts()` to clean up stale instances
1220- Ensure all server instances use the same configuration when accessing shared directories
1221- Monitor server health with `get_server_health()` for instance tracking information
1222 
1223---
1224 
1225## Configuration
1226 
1227OpenZIM MCP supports configuration through environment variables with the `OPENZIM_MCP_` prefix:
1228 
1229```bash
1230# Cache configuration
1231export OPENZIM_MCP_CACHE__ENABLED=true
1232export OPENZIM_MCP_CACHE__MAX_SIZE=200
1233export OPENZIM_MCP_CACHE__TTL_SECONDS=7200
1234 
1235# Content configuration
1236export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000
1237export OPENZIM_MCP_CONTENT__SNIPPET_LENGTH=2000
1238export OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT=20
1239 
1240# Logging configuration
1241export OPENZIM_MCP_LOGGING__LEVEL=DEBUG
1242export OPENZIM_MCP_LOGGING__FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
1243 
1244# Server configuration
1245export OPENZIM_MCP_SERVER_NAME=my_openzim_mcp_server
1246```
1247 
1248### Configuration Options
1249 
1250| Setting | Default | Description |
1251|---------|---------|-------------|
1252| `OPENZIM_MCP_CACHE__ENABLED` | `true` | Enable/disable caching |
1253| `OPENZIM_MCP_CACHE__MAX_SIZE` | `100` | Maximum cache entries |
1254| `OPENZIM_MCP_CACHE__TTL_SECONDS` | `3600` | Cache TTL in seconds |
1255| `OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH` | `100000` | Max content length |
1256| `OPENZIM_MCP_CONTENT__SNIPPET_LENGTH` | `1000` | Max snippet length |
1257| `OPENZIM_MCP_CONTENT__DEFAULT_SEARCH_LIMIT` | `10` | Default search result limit |
1258| `OPENZIM_MCP_LOGGING__LEVEL` | `INFO` | Logging level |
1259| `OPENZIM_MCP_LOGGING__FORMAT` | `%(asctime)s - %(name)s - %(levelname)s - %(message)s` | Log message format |
1260| `OPENZIM_MCP_SERVER_NAME` | `openzim-mcp` | Server instance name |
1261 
1262---
1263 
1264## Security Features
1265 
1266- **Path Traversal Protection**: Secure path validation prevents access outside allowed directories
1267- **Input Sanitization**: All user inputs are validated and sanitized
1268- **Resource Management**: Proper cleanup of ZIM archive resources
1269- **Error Handling**: Sanitized error messages prevent information disclosure
1270- **Type Safety**: Full type annotations prevent type-related vulnerabilities
1271 
1272---
1273 
1274## Performance Features
1275 
1276- **Intelligent Caching**: LRU cache with TTL for frequently accessed content
1277- **Resource Pooling**: Efficient ZIM archive management
1278- **Optimized Content Processing**: Fast HTML to text conversion
1279- **Lazy Loading**: Components initialized only when needed
1280- **Memory Management**: Proper cleanup and resource management
1281 
1282---
1283 
1284## Testing
1285 
1286The project includes comprehensive testing with 80%+ coverage using both mock data and real ZIM files:
1287 
1288### Test Categories
1289 
1290- **Unit Tests**: Individual component testing with mocks
1291- **Integration Tests**: End-to-end functionality testing with real ZIM files
1292- **Security Tests**: Path traversal and input validation testing
1293- **Performance Tests**: Cache and resource management testing
1294- **Format Compatibility**: Testing with various ZIM file formats and versions
1295- **Error Handling**: Testing with invalid and malformed ZIM files
1296 
1297### Test Infrastructure
1298 
1299OpenZIM MCP uses a hybrid testing approach:
1300 
13011. **Mock-based tests**: Fast unit tests using mocked libzim components
13022. **Real ZIM file tests**: Integration tests using official zim-testing-suite files
13033. **Automatic test data management**: Download and organize test files as needed
1304 
1305### Test Data Sources
1306 
1307- **Built-in test data**: Basic test files included in the repository
1308- **zim-testing-suite integration**: Official test files from the OpenZIM project
1309- **Environment variable support**: `ZIM_TEST_DATA_DIR` for custom test data locations
1310 
1311```bash
1312# Run tests with coverage report
1313make test-cov
1314 
1315# View coverage report
1316open htmlcov/index.html
1317 
1318# Run comprehensive tests with real ZIM files
1319make test-with-zim-data
1320```
1321 
1322### Test Markers
1323 
1324Tests are organized with pytest markers:
1325 
1326- `@pytest.mark.requires_zim_data`: Tests requiring ZIM test data files
1327- `@pytest.mark.integration`: Integration tests
1328- `@pytest.mark.slow`: Long-running tests
1329 
1330---
1331 
1332## Monitoring
1333 
1334OpenZIM MCP provides built-in monitoring capabilities:
1335 
1336- **Health Checks**: Server health and status monitoring
1337- **Cache Metrics**: Cache hit rates and performance statistics
1338- **Structured Logging**: JSON-formatted logs for easy parsing
1339- **Error Tracking**: Comprehensive error logging and tracking
1340 
1341---
1342 
1343## Versioning
1344 
1345This project uses [Semantic Versioning](https://semver.org/) with automated version management through [release-please](https://github.com/googleapis/release-please).
1346 
1347### Automated Releases
1348 
1349Version bumps and releases are automated based on [Conventional Commits](https://www.conventionalcommits.org/):
1350 
1351- **`feat:`** - New features (minor version bump)
1352- **`fix:`** - Bug fixes (patch version bump)
1353- **`feat!:`** or **`BREAKING CHANGE:`** - Breaking changes (major version bump)
1354- **`perf:`** - Performance improvements (patch version bump)
1355- **`docs:`**, **`style:`**, **`refactor:`**, **`test:`**, **`chore:`** - No version bump
1356 
1357### Release Process
1358 
1359The project uses an **improved, consolidated release system** with automatic validation:
1360 
13611. **Automatic** (Recommended): Push conventional commits → Release Please creates PR → Merge PR → Automatic release
13622. **Manual**: Use GitHub Actions UI for direct control over releases
13633. **Emergency**: Push tags directly for critical fixes
1364 
1365**Key Features:**
1366 
1367- **Zero-touch releases** from main branch
1368- **Automatic version synchronization** validation
1369- **Comprehensive testing** before every release
1370- **Improved error handling** and rollback capabilities
1371- **Branch protection** prevents broken releases
1372 
1373For detailed instructions, see [Release Process Guide](docs/RELEASE_PROCESS_GUIDE.md).
1374 
1375### Commit Message Format
1376 
1377```
1378<type>[optional scope]: <description>
1379 
1380[optional body]
1381 
1382[optional footer(s)]
1383```
1384 
1385**Examples:**
1386 
1387```bash
1388feat: add search suggestions endpoint
1389fix: resolve path traversal vulnerability
1390feat!: change API response format
1391docs: update installation instructions
1392```
1393 
1394---
1395 
1396## Contributing
1397 
13981. Fork the repository
13992. Create a feature branch (`git checkout -b feature/amazing-feature`)
14003. Make your changes
14014. Run tests (`make check`)
14025. **Use conventional commit messages** (`git commit -m 'feat: add amazing feature'`)
14036. Push to the branch (`git push origin feature/amazing-feature`)
14047. Open a Pull Request
1405 
1406### Development Guidelines
1407 
1408- Follow PEP 8 style guidelines
1409- Add type hints to all functions
1410- Write tests for new functionality
1411- Update documentation as needed
1412- **Use conventional commit messages** for automatic versioning
1413- Ensure all tests pass before submitting
1414 
1415---
1416 
1417## License
1418 
1419This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
1420 
1421---
1422 
1423## Acknowledgments
1424 
1425- [Kiwix](https://www.kiwix.org/) for the ZIM format and libzim library
1426- [MCP](https://modelcontextprotocol.io/) for the Model Context Protocol
1427- The open-source community for the excellent libraries used in this project
1428 
1429---
1430 
1431Made with ❤️ by [Cameron Rye](https://rye.dev)
1432