Skip to content

Latest commit

 

History

History
387 lines (298 loc) · 8.25 KB

SIMPLE_MODE_GUIDE.md

File metadata and controls

387 lines (298 loc) · 8.25 KB

OpenZIM MCP Simple Mode Guide

Overview

OpenZIM MCP supports two distinct modes to accommodate different LLM capabilities:

  1. Simple Mode (default): Provides just 1 primary intelligent tool that accepts natural language queries
  2. Advanced Mode: Exposes all 18 specialized MCP tools for maximum control and flexibility

Why Simple Mode?

Simple mode is designed for:

  • LLMs with limited tool-calling capabilities: Some models struggle with managing many tools
  • Reduced context window usage: Fewer tools mean less context consumed by tool definitions
  • Simpler integration: Easier to integrate with basic MCP clients
  • Natural language interface: More intuitive for conversational AI applications

Enabling Simple Mode

Command Line

# Simple mode (default)
python -m openzim_mcp /path/to/zim/files
# or explicitly
python -m openzim_mcp --mode simple /path/to/zim/files

# Advanced mode
python -m openzim_mcp --mode advanced /path/to/zim/files

Environment Variable

export OPENZIM_MCP_TOOL_MODE=simple
python -m openzim_mcp /path/to/zim/files

MCP Client Configuration

For Claude Desktop or other MCP clients:

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

Or using environment variable:

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

Simple Mode Tools

zim_query

The primary tool for all ZIM content operations. It accepts natural language queries and intelligently routes them to the appropriate underlying operations.

Parameters:

  • query (required): Natural language query describing what you want
  • zim_file_path (optional): Path to ZIM file (auto-selects if only one exists)
  • limit (optional): Maximum number of results for search/browse operations
  • offset (optional): Starting offset for pagination
  • max_content_length (optional): Maximum content length for articles

Supported Query Types:

File Listing

"list files"
"what ZIM files are available"
"show available archives"

Metadata

"metadata for wikipedia.zim"
"info about this ZIM file"
"details of the archive"

Main Page

"show main page"
"get home page"
"display start page"

Namespaces

"list namespaces"
"what namespaces exist"
"show available namespaces"

Browsing

"browse namespace C"
"show articles in namespace A"
"explore namespace C with limit 20"

Article Structure

"structure of Biology"
"outline of Evolution"
"show sections of Protein"

Article Summary

"summary of Biology"
"summarize Evolution"
"overview of Protein"
"brief of DNA"

Table of Contents

"table of contents for Biology"
"toc of Evolution"
"contents of Protein"

Links Extraction

"links in Biology"
"references from Evolution"
"show related articles in Protein"

Search Suggestions

"suggestions for bio"
"autocomplete evol"
"hints for prot"

Filtered Search

"search evolution in namespace C"
"find biology in type text/html"
"search protein in namespace C type text/html"

Get Article

"get article Biology"
"show Evolution"
"read Protein"
"display article on DNA"

General Search

"search for biology"
"find evolution"
"look for protein"

Examples

Basic Usage

{
  "name": "zim_query",
  "arguments": {
    "query": "list files"
  }
}

Search with Auto-Selection

If only one ZIM file exists, you don't need to specify the path:

{
  "name": "zim_query",
  "arguments": {
    "query": "search for biology"
  }
}

Search with Specific File

{
  "name": "zim_query",
  "arguments": {
    "query": "search for biology",
    "zim_file_path": "/path/to/wikipedia.zim",
    "limit": 5
  }
}

Get Article Content

{
  "name": "zim_query",
  "arguments": {
    "query": "get article Evolution",
    "zim_file_path": "/path/to/wikipedia.zim",
    "max_content_length": 5000
  }
}

Browse Namespace

{
  "name": "zim_query",
  "arguments": {
    "query": "browse namespace C",
    "zim_file_path": "/path/to/wikipedia.zim",
    "limit": 20,
    "offset": 0
  }
}

Get Article Structure

{
  "name": "zim_query",
  "arguments": {
    "query": "structure of Biology",
    "zim_file_path": "/path/to/wikipedia.zim"
  }
}

Get Article Summary

{
  "name": "zim_query",
  "arguments": {
    "query": "summary of Evolution",
    "zim_file_path": "/path/to/wikipedia.zim"
  }
}

Get Table of Contents

{
  "name": "zim_query",
  "arguments": {
    "query": "table of contents for Biology",
    "zim_file_path": "/path/to/wikipedia.zim"
  }
}

Intent Parsing

The zim_query tool uses intelligent intent parsing to understand your query:

  1. Keyword Matching: Looks for specific keywords like "search", "get", "browse", etc.
  2. Pattern Recognition: Identifies patterns like "X in namespace Y"
  3. Parameter Extraction: Extracts article names, namespaces, and other parameters
  4. Priority Ordering: More specific patterns are checked first
  5. Fallback: Defaults to search if intent is unclear

Comparison: Advanced vs Simple Mode

Aspect Advanced Mode Simple Mode
Number of Tools 18 specialized tools 1 primary tool
Interface Explicit tool selection Natural language queries
Context Usage Higher (all tool definitions) Lower (minimal tool definitions)
Flexibility Maximum control Simplified interface
Learning Curve Steeper (need to know which tool to use) Gentler (just describe what you want)
Best For Advanced LLMs, power users Simple LLMs, conversational AI

Advanced Mode Tools (for reference)

When in advanced mode, these 18 tools are available:

  1. list_zim_files - List all ZIM files
  2. search_zim_file - Search within ZIM file
  3. get_zim_entry - Get specific entry content
  4. get_zim_metadata - Get ZIM file metadata
  5. get_main_page - Get main page entry
  6. list_namespaces - List available namespaces
  7. browse_namespace - Browse entries in namespace
  8. search_with_filters - Advanced filtered search
  9. get_search_suggestions - Auto-complete suggestions
  10. get_article_structure - Extract article structure
  11. extract_article_links - Extract article links
  12. get_entry_summary - Get concise article summary
  13. get_table_of_contents - Extract hierarchical TOC
  14. get_binary_entry - Retrieve binary content (images, PDFs, etc.)
  15. get_server_health - Server health and statistics
  16. get_server_configuration - Server configuration
  17. diagnose_server_state - Comprehensive diagnostics
  18. resolve_server_conflicts - Resolve server conflicts

Tips for Using Simple Mode

  1. Be Descriptive: The more descriptive your query, the better the intent parsing
  2. Use Quotes: For specific article names, use quotes: "get article \"C/Biology\""
  3. Specify Limits: Add "with limit X" to control result count
  4. Auto-Selection: If you have only one ZIM file, you can omit the file path
  5. Fallback to Search: If intent is unclear, the tool defaults to search

Troubleshooting

Query Not Understood

If your query isn't understood correctly:

  1. Try being more explicit: "search for X" instead of just "X"
  2. Use keywords from the supported query types
  3. Check the response for suggestions
  4. Fall back to more specific queries

Wrong Operation Executed

If the wrong operation is executed:

  1. Use more specific keywords
  2. Check the intent parsing patterns in the documentation
  3. Try rephrasing your query
  4. Consider using advanced mode for precise control

Migration Between Modes

You can switch between modes at any time by changing the configuration:

# Switch to advanced mode
export OPENZIM_MCP_TOOL_MODE=advanced

# Switch to simple mode (default)
export OPENZIM_MCP_TOOL_MODE=simple
# or
unset OPENZIM_MCP_TOOL_MODE  # defaults to simple

No data migration is needed - both modes use the same underlying operations and data.