# Reported issues for calibre-mcp

Pod holds 24 of 87 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 [calibre-mcp](/mcp/calibre-mcp).

## Most discussed

### Probe: ImageContent rendering + payload caps in Claude Desktop

## Question
HITL probe on Artem's Desktop via a dev .mcpb (mcpb-dev skill): do figure ImageContent blocks render in chat? Does the model demonstrably SEE them (ask it to describe a diagram)? Where does Desktop actually choke on payload size (validate the ~2 MB cap; find the real ceiling)? Does detail:high visibly improve label readability on a dense diagram? Record facts like spike #21 did. Done = verdict comment + any cap adjustments filed against the tool.

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/80) · 2026-07-22 · closed · 7 comments

### feat: figures widget — fetch mirror per approved mockup

## Question

Implement the widget: new `src/ui/figures-html.ts` built from the frozen **v2** mockup (`docs/dev/design/figures-widget-v2.html` — reading pane + margin rail, #114; the v1 contact sheet in #110 is superseded), registered as a `ui://` app resource and attached to `calibre_get_figures` via `_meta.ui.resourceUri`.

**Wire the MCP plumbing into the v2 mockup, don't redesign it.** The mockup leaves four seams (`figures-widget-v2.html:191`): `window.FIG.render(payload)`, `onToggleZoom(idx

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/112) · 2026-07-27 · closed · 4 comments

### get_content and content-layer tools fail after client restart while ping succeeds; missing @huggingface/transformers breaks more than semantic search

## Summary
After a Claude Desktop restart, content-related tools consistently fail with a generic tool execution error, while calibre_ping succeeds. Metadata and content tools (calibre_get_content, calibre_search mode=fts, calibre_get_book) all return errors on every call.

## Environment
- Client: Claude Desktop (macOS)
- Library: Programming_Books (~800 books), Calibre GUI + Content Server running on :8080
- Book used for repro: id 164, PDF (Software Architecture Metrics, OReilly)

## Repro / 

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/73) · 2026-07-21 · closed · 3 comments

### Search-inside buttons vanish after a successful click — ui/message success misread as failure

## What happened

In Claude Desktop (v0.6.0), clicking **Search inside** on the cover board sends the message to chat correctly (the assistant starts searching inside the book) — but afterwards the Search-inside affordance disappears from **every** card in the widget, in both the shelf and coverflow variants. Re-entering the chat restores them.

## What I expected

A successful click leaves the buttons in place. The message-backed buttons should only hide when the host genuinely can't deliver ch

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/72) · 2026-07-21 · closed · 3 comments

### Clicked Read button disappears from the book card after use (Claude Desktop)

## What happened

In Claude Desktop (v0.6.0 bundle), clicking a per-format **Read** button (e.g. Read PDF) on the book card opens Desktop's open-link confirmation dialog — and the clicked button disappears from the card. It happens regardless of whether the dialog is approved (book opens in the browser) or dismissed. Only the clicked button vanishes; the other format's Read/⬇ pair and the rest of the card stay. Leaving and re-entering the chat restores the button.

## What I expected

The button

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/69) · 2026-07-21 · closed · 3 comments

### calibre_ping semantic-status fields (one-call diagnosis)

## Question

Extend `calibre_ping` with a semantic-status block so "why is semantic search not working" is a one-call diagnosis (#41 follow-up ¶1). Candidate fields: model id, dim, dependency resolvable?, model cached on disk?, index vector count. Locked: ping fields, NOT a new `semantic_status` tool (tool-count policy). Sharpen the exact field shapes here (the map's Not-yet-specified item), mirror the essentials into the text block. Execution carried.

Part of wayfinder map #43 (resolving #41).

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/48) · 2026-07-19 · closed · 3 comments

### Universal remediation message for the missing embedding model

## Question

Replace the dev-only "pnpm add @huggingface/transformers" advice (#41 problem 2) with one universal message covering all three installs — .mcpb extension (`npm install @huggingface/transformers` inside the extension dir, or reinstall), npx/npm (reinstall without `--omit=optional`), dev checkout (`pnpm add`). Locked: no runtime bundle-detection code — the reading LLM picks the branch. Touch points: `mapError` in `src/tools/calibre_semantic_search.ts`, the build notes in `src/tools/ca

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/47) · 2026-07-19 · closed · 3 comments

### Release: figures widget ships + Desktop verification

## Question

Ship the widget in a public release (version per the map's cadence note — coordinate with the Bundles map #94; `release` agent does the cut), then verify the released .mcpb in Claude Desktop: a real `calibre_get_figures` fetch renders the mirror widget with the same figures. Closes the map.

Blocked by: #112

Map: #109

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/113) · 2026-07-27 · closed · 2 comments

## Most recent

### Expose index generation (INDEX_VERSION) as citation provenance in semantic-search results + calibre_ping

### Problem

`calibre_semantic_search` returns locations (`bookId`, `format`, `charStart`/`charEnd`, and
`page` for figure hits) that are only meaningful **relative to the extraction + chunker
generation that produced the index**. That generation is tracked internally as
`INDEX_VERSION` (`src/semantic/model.ts:147`) and written into the index `meta` table
alongside `model_id`/`dim` (`src/semantic/store.ts:808`), but it is not exposed anywhere a
client can read:

- not in `calibre_semantic_search

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/136) · 2026-08-27 · open · 0 comments

### feat(structure): EPUB TOC (nav.xhtml/NCX) as a chapter-map source — needs spine-aware extraction

## Problem

An EPUB carries the best chapter structure of any format we handle — an explicit, authored
`nav.xhtml` (EPUB 3) or NCX (EPUB 2) table of contents, with real titles pointing at real
spine documents. We use **none of it**. Chapter detection
(`src/domain/structure/chapters.ts`) runs the same text heuristics over an EPUB as over a
scanned PDF, so a book whose TOC says "The Carpet-Bag" only gets a chapter span if that
string happens to look like a heading in the converted plain text.

## 

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/135) · 2026-08-21 · open · 0 comments

### feat(structure): use the PDF outline (bookmarks) as a chapter-map source

## Problem

Chapter detection (`src/domain/structure/chapters.ts`) is **purely text-based**: explicit
headings (`Chapter 5` / `Kapitel 5` / `Глава 5` / `第5章`), Roman numerals, or Markdown
`#`/`##`. A PDF that carries a perfectly good publisher outline (bookmarks) but never
writes the word "Chapter" in its body text comes back `detector: "none"` — no chapter map
for `calibre_get_content` mode=structure, no chapter walk for `calibre-distill`, and search
hits labelled by raw offset instead of a cha

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/134) · 2026-08-21 · open · 0 comments

### feat(extract): support ODT books (ebook-convert already handles them)

`FORMAT_PREFERENCE` in `src/calibre/extract.ts` currently ends at
`… docx, htmlz, fb2, rtf` — **`odt` is missing**, so a book whose only format is ODT is
reported as *"no extractable text format"* by `calibre_get_content`, `calibre_build_index`
and ISBN scanning, exactly like the `md` gap fixed in #131 / v0.7.4.

ODT is a first-class **input** format for Calibre's `ebook-convert` (the same backend that
already handles EPUB/MD/DOCX here), so this should be a one-line addition plus a test —
no new

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/132) · 2026-08-21 · open · 0 comments

### ui: clicking a cover on the cover board does nothing visible in Claude Desktop (widget-initiated tools/call result never reaches the chat)

## Symptom (Claude Desktop, live, 2026-08-18)

On the cover board (both shelf and coverflow), clicking a cover — the centered one in coverflow — shows the "Opening…" overlay for ~1.4 s and then **nothing happens**. No book card appears in the chat.

Reproduced while recording the new demo GIF: `which of my books explain consumer-group rebalancing?` → coverflow → click centered cover → nothing.

## Cause

`src/ui/board-html.ts` `onCardClick(bookId)` does a **widget-initiated** `tools/call calibre

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/130) · 2026-08-18 · closed · 1 comment

### Task: seed initial bundles + exclusion markers for Artem's library (curation session)

## Question

Run the first curation session over the real library (791 books): decide and create the initial topic bundles (e.g. rust, databases, architecture, ai/llm — drive from `calibre_list_categories` tag counts and `calibre_quality_report`) and the first `-` exclusion markers (noise/outdated books). HITL: bundle boundaries and what counts as noise are Artem's calls; the agent proposes from tag statistics, Artem confirms, `calibre_manage_bundles` writes. Done = a confirmed starter set live 

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/126) · 2026-08-03 · open · 0 comments

### Release: v2-based calibre-mcp ships + Desktop verification on the released bundle

## Question

Ship it and prove it live.

Cut the release via the `release` agent (version shape decided at this point, per the map's *Not yet specified*): version bump across all spots including `manifest.json` and `.claude-plugin/plugin.json`, CHANGELOG entry, tag, CI publish; then verify **npm + `.mcpb` + MCP Registry `isLatest`**.

Then verify live in **Claude Desktop on the released bundle**, not a dev one:

- server connects and all 18 tools are listed;
- a read round-trips (`calibre_search

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/125) · 2026-07-28 · open · 0 comments

### Task: verify the .mcpb bundle under v2 — staging npm install, bundle size, Desktop install

## Question

Does the `.mcpb` bundle still build, install, and run under v2 — and at what size?

`scripts/pack-mcpb.mjs` stages a curated tree and runs a real `npm install --omit=dev --omit=optional` because `mcpb pack` zips `node_modules` verbatim and pnpm's symlinked layout can't be zipped. v2 changes that tree: two packages instead of one, each shipping **both** ESM and CJS builds, plus `ext-apps` at whatever peer range the migration settled on.

Answer with measurements from a dev bundle (`p

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/124) · 2026-07-28 · open · 0 comments

### feat: migrate to the v2 SDK packages (wire unchanged)

## Question

Land the migration on `main`: calibre-mcp built on `@modelcontextprotocol/server` + `@modelcontextprotocol/core`, wire unchanged.

Per the decisions this ticket is blocked on (ext-apps policy, seam shape), apply the codemod result for real, hand-fix every `@mcp-codemod-error` site, and prove nothing regressed:

- `pnpm build`, `pnpm test`, `pnpm typecheck` green;
- the retrieval eval gate green against the untouched baseline (`pnpm eval --gate`) — the migration must not perturb sear

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/123) · 2026-07-28 · open · 0 comments

### Task: interim bump @modelcontextprotocol/sdk 1.29.0 → 1.30.0

## Question

Land the interim `@modelcontextprotocol/sdk` 1.29.0 → **1.30.0** bump, and record whether anything in our seam moved.

This is the only step actionable today: the map can stall on `ext-apps` for weeks, and 1.30.0 is the v1 line's current head with fixes that touch our transport — notably the **stdio buffer limit** ([#2239](https://github.com/modelcontextprotocol/typescript-sdk/pull/2239)), Zod 3.25 method-literal support, and better Zod issue formatting on the server. Wire and API a

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/122) · 2026-07-28 · open · 0 comments

### Grill: does the SDK-free seam survive v2 — keep the hand-written mirror in tools/types.ts or re-export from /core

## Question

Does the SDK-free seam survive v2 as designed, or does it need re-cutting?

`src/tools/types.ts` deliberately holds *structural* copies of the SDK's `CallToolResult` / `ToolAnnotations` / content blocks so 18 tool handlers never import the SDK (CLAUDE.md invariant, DESIGN §7). v2 moved the spec schemas into `@modelcontextprotocol/core` and changed several public types (`RequestHandlerExtra` → `ServerContext`, `extra` → `ctx`, `McpError` → `ProtocolError`, `IsomorphicHeaders` → web `

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/121) · 2026-07-28 · open · 0 comments

### Task: codemod dry-run on a throwaway branch — measure the real v1→v2 change surface

## Question

What is the **actual** change surface of the v1→v2 migration in this repo — measured, not estimated?

Run `npx @modelcontextprotocol/codemod@latest v1-to-v2 .` at the package root on a throwaway branch (never `main`), then record:

- every file the codemod touched, and the diff size — does the SDK-free seam hold at `src/server.ts` + `src/run-stdio.ts`, or does the blast radius reach handlers/tests/scripts?
- every `@mcp-codemod-error` marker (`grep -rn '@mcp-codemod-error' .`) — the

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/120) · 2026-07-28 · open · 0 comments

### Grill: policy for the ext-apps v1 peer block — wait, force the peer, or cut the widgets

## Question

`@modelcontextprotocol/ext-apps@1.7.5` peer-deps `@modelcontextprotocol/sdk: ^1.29.0`, so installing the v2 packages alongside it is a peer conflict. What is our policy while upstream sorts itself out?

Candidates to grill:

- **Wait** — the map parks until `ext-apps` ships a v2-compatible release. Honest, zero risk, indefinite: the map's completion depends on someone else's draft PR.
- **Force the peer** — `pnpm.overrides` / `peerDependencyRules.allowedVersions` to install both, be

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/119) · 2026-07-28 · open · 0 comments

### Wayfinder map: migrate calibre-mcp to SDK v2 packages (wire unchanged)

## Destination

A public release of calibre-mcp built on the **v2 SDK packages** (`@modelcontextprotocol/server` + `@modelcontextprotocol/core` replacing `@modelcontextprotocol/sdk`), with the **wire unchanged** — the server keeps speaking the 2025-11-25 era byte for byte — verified live in Claude Desktop with all three widgets (board, card, figures) working. The map closes when the release is on npm/.mcpb/Registry and Desktop-verified.

## Notes

- **Execution-carrying map** (explicit override 

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/117) · 2026-07-28 · open · 0 comments

### Figure detection: line-start in-text references are read as captions (page-render returns a page of prose)

## Symptom

`calibre_get_figures id=165` (*Modern Processor Design*, Shen & Lipasti — single-column justified PDF) lists 12 "figures", **all** `page-render`, whose captions are visibly body prose, several ending mid-word at a hyphenation point:

```
index | page | source | caption
1 | p.80 | page-render 2.10 | The four sequences of subcomputations required by these four instruc¬
2 | p.82 | page-render 2.10 | This instruction pipeline is identified as the TYPICAL (TYP) instruction
4 | p.102| page

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/116) · 2026-07-27 · closed · 1 comment

### Decide whether the tool description and plugin skill mention the figures widget

## Question

Now that the widget ships on every `calibre_get_figures` fetch: should the **model-facing** surface say so, and where?

- `calibre_get_figures`'s tool description — does the model need to know a fetch also renders the figures to the user (e.g. so it stops describing pixels the user can already see, or so it fetches rather than paraphrasing)? Or is that wasted tool-def tokens and a steering risk?
- the `calibre-mcp` plugin skill / `docs/TOOLS.md` — same call for the human-facing docs

[Read the thread](https://github.com/caelum29/calibre-mcp/issues/115) · 2026-07-27 · closed · 1 comment

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