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.

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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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), Zod 3.25 method-literal support, and better Zod issue formatting on the server. Wire and API a

Read the thread · 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 · 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 · 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 · 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 · 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).