# ZIM RAG MCP Server

MCP (Model Context Protocol) server for reading `.zim` archives and exposing
search/content retrieval tools over stdio.

## What This Server Provides

- ZIM file discovery from a configured directory
- Metadata and article listing tools
- Title/url search
- Article content retrieval
- TF-IDF based RAG retrieval over extracted article chunks

## Project Layout

- `server.py` - MCP stdio server and tool/resource handlers
- `zim_reader.py` - binary ZIM parser and article extraction
- `rag_engine.py` - chunking + TF-IDF retrieval engine
- `requirements.txt` - Python dependencies

## Requirements

- Python 3.10+
- A directory containing one or more `.zim` files

Install dependencies:

```bash
pip install -r requirements.txt
```

## Run Locally

From this folder (`MCPs/ZIM_MCP`):

```bash
python server.py
```

Environment variable:

- `ZIM_DIRECTORY` (optional): directory containing `.zim` files
  - default: current working directory

Example:

```bash
set ZIM_DIRECTORY=E:\ZIMs
python server.py
```

## MCP Client Configuration

Use script execution (not `-m MCPs.ZIM_MCP`), because this package does not
define `__main__.py`.

### Example (Windows / Cline-style JSON)

```json
{
  "mcpServers": {
    "ZIM-MCP": {
      "type": "stdio",
      "command": "C:\\Program Files\\Python310\\python.exe",
      "args": [
        "e:\\ZIM-MCP\\MCPs\\ZIM_MCP\\server.py"
      ],
      "env": {
        "ZIM_DIRECTORY": "e:\\ZIMs"
      },
      "timeout": 60,
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

## Tools

- `list_zim_files`
  - List `.zim` files discovered in `ZIM_DIRECTORY`.
- `zim_info`
  - Return metadata and namespace counts for a specific ZIM file.
- `zim_search`
  - Search by title/url substring.
- `zim_get_article`
  - Return article title/url/content.
- `zim_rag_retrieve`
  - Return top semantic matches from TF-IDF retrieval.
- `zim_list_articles`
  - Paginated article list with namespace filter.

## Resource URIs

- `zim://{file}/info`
- `zim://{file}/article/{url}`
- `zim://{file}/search/{query}`
- `zim://{file}/rag/{query}`

## Notes

- RAG indexing now gracefully handles small/stopword-heavy corpora and returns
  empty results instead of crashing.
- ZIM cluster parsing supports common compression formats, including Zstandard
  (via Python `zstandard` package).

## Troubleshooting

- **Server starts but no files found**
  - Verify `ZIM_DIRECTORY` points to the folder that contains `.zim` files.
- **`No module named ...` errors**
  - Reinstall deps: `pip install -r requirements.txt`
- **MCP fails to launch from client**
  - Use the full script path in `args` (`...\\server.py`), not
    `-m MCPs.ZIM_MCP`.

## Author

Garland Glessner (`gglessner@gmail.com`)

## License

GNU General Public License v3 (GPLv3)