# Reported issues for openzim-mcp

Pod holds 10 of 10 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [openzim-mcp](/mcp/openzim-mcp).

## Most discussed

### Tracking: adopt MCP spec 2026-07-28 (Python SDK v2 migration)

## Context

The [2026-07-28 MCP spec revision](https://modelcontextprotocol.io/specification/2026-07-28/changelog) is the "stateless MCP" release: the `initialize` handshake, protocol-level sessions (`Mcp-Session-Id`), SSE resumability (`Last-Event-ID`), and the HTTP GET endpoint are removed; `subscriptions/listen` replaces `resources/subscribe`/`unsubscribe`; a mandatory `server/discover` RPC replaces `initialize`-time capability/identity advertisement; Roots, Sampling, and Logging are deprecat

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/360) · 2026-08-10 · closed · 6 comments

### Raising the mcp ceiling past 2.0.x: seam re-audit checklist (parked — no 2.1 exists)

3.0.0 ships with `mcp[cli]>=2.0.0,<2.1` — held deliberately, because the code performs surgery on 2.0.0 internals that a future 2.x could move without any public-API break. CI resolves the lockfile and stays green either way; fresh installs (pip/uvx, Smithery, Glama Docker) resolve the newest admitted wheel, which is the lockfile-masks-range-defects failure mode this project has hit before. Raising the ceiling is a deliberate bump PR that walks this checklist:

- [x] ~~**`sdk_compat.py` ping shi

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/371) · 2026-08-20 · open · 4 comments

### Re-evaluate the deferred 2026-07-28 schema capabilities (outputSchema/structuredContent, zim_search oneOf)

Split from #360 (Phase 4 optionals) so the 3.0.0 tracking issue could close. Both were deferred, not decided — this issue is the decision.

## 1. Real `outputSchema` + `structuredContent` from the `tool_schemas.py` TypedDicts

Dropped originally for two reasons that are both gone: the FastMCP-1.x wrapper (replaced by SDK v2, which supports full JSON Schema 2020-12) and the token budget. The budget, however, has a hard constraint the re-evaluation must start from: **the advanced surface sits at 2

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/370) · 2026-08-20 · closed · 3 comments

### HVTrust evaluation for Openzim MCP: Grade B (70.8/100), ranked 23 of 718 MCP servers

Hi — I maintain [HVTracker](https://hvtracker.net), an independent trust registry for AI agents and MCP servers. Projects are scored from public signals only (OSSF Scorecard, build provenance, signed commits, maintenance cadence, distribution reach). No self-reporting, no submission required, no paid placement.

**Openzim MCP** ranks near the top of the MCP servers we track, so I wanted to send you the result directly rather than just publish it.

[![HVTrust score](https://hvtracker.net/badge/op

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/353) · 2026-08-09 · closed · external user · 3 comments

### [Bug]: Stale ZIM file list after adding archives while cache is enabled

### Pre-submission Checklist

- [x] I have searched existing issues to avoid duplicates
- [x] I have updated to the latest version and the issue persists
- [x] I have read the documentation and troubleshooting guides

### Bug Description

When a new `.zim` file is added to an allowed directory at runtime, tool/resource results don't show it until the server restarts or the cache TTL expires.

### Steps to Reproduce

1. Start `openzim-mcp` with caching enabled and an allowed ZIM directory.
2. Cal

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/307) · 2026-06-29 · closed · external user · 2 comments

### Drop the legacy sse transport

## Context

HTTP+SSE has been deprecated as an MCP transport since the 2025-03-26 revision replaced it with Streamable HTTP, and the [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/changelog) removes the protocol machinery it rode on (the HTTP GET endpoint, SSE resumability via `Last-Event-ID`, protocol-level sessions). The v2 port (#360, #362) deliberately kept `--transport sse` serving: the SDK still ships the transport, and removing a working transport is a user

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/366) · 2026-08-13 · open · 1 comment

### v2.5: tune zim_get descriptions for natural-language summary/structure/main-page dispatch

## Background

The v2.0.0rc1 Stage E1 dispatch sweep (Qwen3-8B-Q4 against the 512-probe Gate 0b set, 5 reps) cleared the F2 enforcement gate (`f2_pass=true`, `failures=[]`) but three new-in-Phase-F operation classes showed low absolute dispatch accuracy:

| Class | Accuracy | n / 5 reps | Where the model goes instead |
| --- | --- | --- | --- |
| `zim_get-summary` | **20%** (20/100) | 20 probes | 80/100 → `zim_query` |
| `zim_get-structure` | **53%** (56/105) | 21 probes | 49/105 → `zim_query` |

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/199) · 2026-05-27 · closed · 1 comment

### [Feature]: Allow LLMs to query file list to avoid filling context

### Pre-submission Checklist

- [x] I have searched existing issues and discussions for similar requests
- [x] I have read the project documentation and roadmap
- [x] This feature aligns with the project's goals and scope

### Problem Statement

If a filepath is not specified the project automatically spits out a list of available files. For a small list of <25 zim files perhaps this is fine, however when a query returns a list of 200, for instance, it wastes context space and user time. list_zi

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/81) · 2026-05-01 · closed · external user · 1 comment

## Most recent

### zim_search: flat schema vs oneOf mode-conditional shape (Gate 0.3 re-run)

Split from #370, which closed part 1 (`outputSchema`/`structuredContent`) as not-planned on measured per-call cost. Part 2 is unrelated to that decision and is the only live content left, so it moves here.

## The question

`zim_search`'s input schema is flat: every mode's parameters are siblings, and which ones apply is described in prose. The alternative is a `oneOf` that makes the mode-conditional shape structural, so a client can only send a coherent combination.

The protocol constraint tha

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/395) · 2026-08-25 · open · 0 comments

### feat: Add binary content retrieval for embedded media (PDFs, videos, images)

## Summary

Add the ability to retrieve raw binary content from ZIM entries, enabling integration with external tools for processing embedded media like PDFs, videos, and images.

## Background

A user building a knowledge agent identified a gap in the current implementation: while openzim-mcp can **discover** embedded content (via `extract_article_links` which finds media links), there's no way to **retrieve** the raw binary data to pass to other tools for processing.

Many ZIM archives contain

[Read the thread](https://github.com/cameronrye/openzim-mcp/issues/45) · 2026-01-28 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/cameronrye/openzim-mcp/issues).