Calibre MCP Server & Recherche-Plugin

Ein experimenteller Model Context Protocol (MCP) Server, der auf eine lokale Calibre Bibliothek zugreift. Ziel ist es, KI-Agenten (z. B. ChatGPT, Copilot, Claude Desktop) ein Research-API auf deine E‑Book‑Sammlung zu geben – inklusive Volltextsuche und strukturierten Excerpts.

Zusätzlich gibt es ein Calibre‑GUI‑Plugin, das

• den MCP‑Server als WebSocket-Dienst startet (ws://127.0.0.1:8765) und
• einen Recherche‑Agenten bereitstellt, der
  • Volltext‑Tools des MCP‑Servers verwendet,
  • Schlagworte per LLM ableitet und
  • Antworten inkl. Quellen (Titel + ISBN) im Calibre‑Dialog anzeigt.

---

Features (aktueller Stand)

MCP‑Server

• Implementiert mit fastmcp
• Bietet aktuell zwei Tools an:
  • calibre_fulltext_search
    • Eingabe: query: str, limit: int
    • Liefert Treffer (book_id, title, isbn, snippet)
    • Sucht in metadata.db über books + comments (Titel, ISBN, Kommentare)
  • calibre_get_excerpt
    • Eingabe: isbn: str, max_chars: int
    • Liefert einen kurzen Textausschnitt plus Metadaten (book_id, title)
• Domänenschicht LibraryResearchService als zentrale API
• Zugriff auf Calibre‑metadata.db via SQLite (read‑only)
  • ISBN‑Lookup über identifiers + Fallback auf books.isbn

Calibre‑Plugin mcp_server_recherche

• Startet / stoppt den MCP‑Server über WebSocket (ws://host:port)
• Stellt einen Recherche‑Dialog bereit, der
  • Fragen an einen konfigurierten LLM‑Provider sendet,
  • automatisch MCP‑Tools für Volltextsuche und Excerpts nutzt,
  • Suchtreffer und Auszüge anzeigt und
  • eine strukturierte Antwort mit Quellen (inkl. ISBN) generiert.
• Unterstützt Follow‑up‑Fragen:
  • Kurze Nachfragen werden mit der vorherigen Frage kombiniert (z. B. „Sag mir mehr zu LIN (im Kontext von: Welche Fahrzeug‑Bussysteme gibt es?)“).
  • Der Agent sucht erneut in der Bibliothek, nutzt aber den bisherigen Kontext.
• Debug‑Ausgabe im Dialog (optional), z. B.:
  • Suchrunde 1 (Kernbegriffe): ['hacking', 'Sicherheit', ...]
  • Toolcall calibre_fulltext_search: query='hacking', limit=6
  • MCP -> list_tools, MCP <- call_tool usw.

---

Repository‑Struktur (Kurzüberblick)

Wichtige Verzeichnisse/Dateien:

• pyproject.toml – Projekt‑ und Dependency‑Definitionen
• src/calibre_mcp_server/ – MCP‑Server und Domänencode
  • core/models.py – einfache Domain‑Modelle (FulltextHit, Excerpt, ...)
  • core/service.py – LibraryResearchService, zentrale Research‑API
  • infra/metadata_sqlite.py – Zugriff auf metadata.db über SQLite
  • tools/ft_search_tool.py – MCP‑Tool calibre_fulltext_search
  • tools/excerpt_tool.py – MCP‑Tool calibre_get_excerpt
  • websocket_server.py – kleiner WebSocket‑RPC‑Server für MCP‑Calls
  • mcp_protocol.py – einfache MCP‑Request/Response‑Strukturen
  • main.py – Einstiegspunkt für den Server
• calibre_plugin/ – Calibre‑GUI‑Plugin
  • __init__.py – Plugin‑Metadaten für Calibre
  • config.py – Plugin‑Einstellungen / UI
  • main.py – Dialog, Recherche‑Agent, Start/Stopp des WebSocket‑Servers
  • providers.py – Konfiguration der LLM‑Provider (OpenAI‑kompatibel, o. Ä.)
  • recherche_agent.py – Orchestrierung von LLM + MCP‑Tools
  • ui.py – Qt‑Dialog und UI‑Logik
• tests/
  • inspect_metadata_isbn.py – Debug‑Script, zeigt ISBN‑Mapping in metadata.db
  • manual_test_websocket_connectivity.py – Testet WS‑Server mit einem einfachen Client

---

Installation (Development Setup)

Voraussetzungen:

• Python 3.10+ (getestet mit 3.12)
• Lokale Calibre‑Bibliothek (mit metadata.db)

Setup (Entwicklungsumgebung):

# Repository klonen
git clone https://github.com/Miguel0888/mcp-server.git
cd mcp-server

# Optional: virtuelles Environment anlegen
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

# Paket im Editable‑Mode installieren (inkl. Dependencies)
python -m pip install --upgrade pip
python -m pip install -e .

Danach ist das Paket calibre_mcp_server im aktiven Python‑Interpreter verfügbar.

---

MCP‑Server manuell starten (WebSocket‑Modus)

Der Calibre‑Plugin‑Workflow startet den Server automatisch. Für manuelle Tests kannst du ihn aber auch direkt ausführen.

1. Konfiguration über Umgebungsvariablen

Der Server liest die Bibliotheks‑Konfiguration aus src/calibre_mcp_server/config.py. Standard: aktuelle Calibre‑Bibliothek oder ein konfigurierten Pfad.

Für einen manuellen Test kannst du z. B. CALIBRE_LIBRARY_PATH setzen:

set CALIBRE_LIBRARY_PATH=X:\E-Books
python -m calibre_mcp_server.main

Der Server startet dann einen WebSocket‑Endpoint, z. B. ws://127.0.0.1:8765, und akzeptiert MCP‑ähnliche Requests (list_tools, call_tool).

2. Tools testen (z. B. via WebSocket‑Client oder Testskript)

Siehe tests/manual_test_websocket_connectivity.py für ein Minimalbeispiel, das:

• eine Verbindung zu ws://127.0.0.1:8765 herstellt,
• list_tools sendet und
• anschließend call_tool für calibre_fulltext_search ausführt.

---

Calibre‑Plugin: Installation & Konfiguration

Plugin‑ZIP bauen (falls nicht über GitHub Release bezogen)

Im Projekt‑Root:

mkdir dist
cd calibre_plugin
zip -r ..\dist\calibre-mcp-plugin.zip .

Die ZIP‑Datei dist/calibre-mcp-plugin.zip enthält dann die Plugin‑Dateien im Root, wie Calibre es erwartet.

Plugin in Calibre installieren

1. Calibre öffnen
2. Einstellungen → Plugins → "Plugin aus Datei laden"
3. dist/calibre-mcp-plugin.zip auswählen
4. Calibre neu starten

Danach erscheint das Plugin (z. B. "MCP‑Recherche") im Menü / der Toolbar.

Wichtige Einstellungen im Plugin

Im Plugin‑Dialog (Einstellungen → Plugins → MCP Server Recherche → Konfigurieren):

• MCP Server Einstellungen
  • Server-Host (Default: 127.0.0.1)
  • Server-Port (Default: 8765)
  • Calibre-Bibliothek (optional fester Pfad; sonst aktive Bibliothek verwenden)
  • Optional: Python‑Interpreter für den MCP‑Server (falls nicht der globale genutzt werden soll)
• Recherche‑Feintuning
  • max_query_variants – Wie viele Varianten an Suchqueries pro Runde maximal genutzt werden.
  • max_hits_per_query – Limit für Treffer pro Query.
  • max_hits_total – Globales Limit an Treffern, die in den Kontext übernommen werden.
  • target_sources – Wie viele unterschiedliche Quellen (Bücher) der Agent mindestens finden soll.
  • max_excerpts / max_excerpt_chars – Anzahl und Länge der Excerpts.
  • min_hits_required – Mindestanzahl an Treffern, bevor die Suche beendet wird.
  • max_search_rounds – Wie viele Suchrunden der Agent maximal macht (z. B. 2: einfache Keywords + Refinement).
  • context_influence – Wie stark vorherige Fragen den Kontext neuer Nachfragen beeinflussen (0–100).
• Prompt‑Hints
  • Hinweis für Query-Planer-Prompt (query_planner_hint)
    • Zusatztext, den du der KI geben kannst, um die Art der Suchqueries zu steuern (z. B. „nutze bevorzugt deutsche Fachbegriffe aus der Fahrzeugtechnik“).
  • Hinweis für Schlagwort-Prompt (keyword_extraction_hint)
    • Feintuning für die Keyword‑Extraktion, z. B. „nutze zunächst breite Begriffe ohne AND, keine langen UND‑Ketten“.
  • Hinweis für Antwort-Prompt (answer_style_hint)
    • Ergänze, wie die Antworten formuliert werden sollen (z. B. „erkläre auf Bachelor‑Niveau“).
• Suchmodus
  • LLM für Query-Planung verwenden – Schaltet die LLM‑gestützte Schlagwort‑/Query‑Planung ein/aus.
  • Max. Schlagwörter pro Suche (max_search_keywords)
  • Verknüpfung (AND/OR) (keyword_boolean_operator) – wird vor allem für klassische, heuristische Queries genutzt.

---

Wie der Recherche‑Agent arbeitet (High‑Level)

Der Kern der Logik steckt in calibre_plugin/recherche_agent.py:

1. Frage normalisieren

   • Leere Eingaben werden ignoriert.
   • Kurze Nachfragen werden mit der vorherigen Frage kombiniert, um Kontext zu erhalten.

2. Suchrunden ausführen

   • Runde 1:
     • _extract_keywords (LLM) erzeugt eine Wortliste / einfache Phrasen.
     • Wenn es nur eine Liste ist (z. B. "hacking cyberangriffe sicherheit …"), werden die Wörter gesplittet und einzeln als Queries ausgeführt (hacking, Sicherheit, ...). → Effektiv eine OR‑Suche über die einzelnen Begriffe.
     • Wenn mehrere Phrasen zurückkommen, wird jede als eigene Query verwendet.
   • Runde 2+ (optional, bis max_search_rounds):
     • _refine_search_queries nutzt den LLM, um auf Basis bisheriger Treffer alternative oder verfeinerte Suchqueries zu erzeugen.
     • Die Ergebnisse werden mit den bisherigen Treffern zusammengeführt und dedupliziert.

3. Treffer mit Excerpts anreichern

   • Für eine begrenzte Anzahl an Treffern mit ISBN ruft der Agent calibre_get_excerpt auf, um kurze Textausschnitte (z. B. aus Kommentaren) zu laden.

4. Prompt bauen & LLM‑Antwort holen

   • Der Agent baut einen Markdown‑Prompt mit drei Teilen:
     1. Kurze Zusammenfassung
     2. Relevante Bücher mit Kurznotizen und ISBN
     3. Ausführliche Beantwortung der Frage
   • Der LLM‑Provider wird über ChatProviderClient angesprochen.

5. Antwort im Dialog anzeigen

   • Der Dialog zeigt die Antwort (Markdown) und optional das Debug‑Log der Tool‑Nutzung.

---

Debugging & Tests

• FT‑Suche direkt testen
  • src/calibre_mcp_server/tools/ft_search_tool.py nutzt LibraryResearchService.fulltext_search.
  • Manuelle Tests kannst du mit einem einfachen WebSocket‑Client oder dem Testskript durchführen.
• ISBN‑Mapping prüfen
  • tests/inspect_metadata_isbn.py hilft zu verstehen, wie Calibre ISBNs in books und identifiers ablegt.

Beispielaufruf:

python tests\inspect_metadata_isbn.py 9783658024192

---

Roadmap / Ideen

• Weitere MCP‑Tools, z. B. für
  • Schlagwort‑Suche (Tags, Serien)
  • Autorensuche
  • Volltextsuche über den tatsächlichen Buchinhalt (sofern indiziert)
• Bessere Unterstützung für Streaming‑Antworten im Calibre‑Dialog
• Konfigurierbare Anzeige von Tool‑Traces (Debugpanel ein-/ausblendbar)
• Erweiterte Mehrphasen‑Strategien für den Recherche‑Agenten (z. B. mehr als 2 Suchrunden, gewichtete Treffer)

---

Dieses Projekt ist experimentell – Feedback, Issues und Pull Requests sind willkommen.