Referenz
Bookheap spricht MCP: Werkzeuge, mit denen ein Agent die Bibliothek liest und pflegt. Der verbindliche Vertrag bleibt agents.md — diese Seite ist die ausführliche Referenz dazu.
https://mcp.prod.bookheap.app/mcpEin 401 mit WWW-Authenticate ist die Eingangstür, kein Fehler: darüber läuft die OAuth-Discovery (RFC 9728, dann RFC 8414, dann RFC 7591).
Der Agent meldet sich über denselben OAuth-Dialog an wie der Mensch und erhält ein befristetes Token mit genau den bestätigten Rechten. Lesen und Schreiben sind getrennt: books/read beantwortet Fragen, books/write trägt ein. Wer nur antwortet, braucht kein Schreibrecht.
Listet die Bücher der Bibliothek, filterbar nach Regal und Stimmung. Beantwortet „Was lese ich gerade?“ und „Was steht auf der Leseliste?“ in einem Aufruf.
| Parameter | Typ | Beschreibung |
|---|---|---|
| status | reading · backlog · finished | Filtert nach Regal: reading (Jetzt), backlog (Nächstes), finished (Fertig). |
| mood | light · deep · short · escape · learn · work | Filtert nach Stimmung. |
AntwortAlle passenden Bücher, vollständig und ohne Cursor.
Holt ein Buch per ID, samt Lesefortschritt. IDs kommen aus list_books; sie sind opake Server-IDs und werden dem Nutzer nie gezeigt.
| Parameter | Typ | Beschreibung |
|---|---|---|
| book_idPflicht | string | Die Server-ID aus list_books. |
AntwortDas Buch mit allen Feldern.
Sucht im öffentlichen Katalog (Open Library) nach Titel, Autor oder ISBN. Vor add_book aufrufen, damit die richtige Ausgabe samt Seitenzahl und Cover mitkommt.
| Parameter | Typ | Beschreibung |
|---|---|---|
| queryPflicht | string | Titel, Autor oder ISBN. |
| limit | integer · 1–10 | Wie viele Kandidaten. Fünf reichen meist, um die richtige Ausgabe zu finden. |
AntwortKandidaten mit Titel, Autor, Jahr, Seitenzahl und Cover.
Legt ein Buch an. Standard ist das Regal Nächstes (backlog) — dort gehört eine Empfehlung hin. status reading nur, wenn der Nutzer schon angefangen hat.
| Parameter | Typ | Beschreibung |
|---|---|---|
| titlePflicht | string | Das einzige Pflichtfeld. |
| author | string | Freitext. |
| status | reading · backlog · finished | Standard ist backlog. |
| mood | light · deep · short · escape · learn · work | Eine der sechs festen Stimmungen. |
| note | string | Herkunft und Anlass — wonach der Nutzer später sucht. |
| page_count | integer | Seitenzahl der Ausgabe; daraus wird der Prozentwert abgeleitet. |
AntwortDas angelegte Buch samt bookId.
Legt viele Bücher in einem Aufruf an — für Goodreads- oder StoryGraph-Exporte, abgetippte Listen, Fotos vom Regal. Deduplizieren ist Sache des Agenten.
| Parameter | Typ | Beschreibung |
|---|---|---|
| booksPflicht | array‹object› · max 100 | Bis zu 100 normalisierte Datensätze mit den Feldern von add_book; größere Importe aufteilen. |
AntwortEin Ergebnis je Datensatz.
Ändert ein Buch: Fortschritt, Regal, Stimmung, Notiz oder eine Korrektur an Titel und Autor. Nur übergebene Felder ändern sich.
| Parameter | Typ | Beschreibung |
|---|---|---|
| book_idPflicht | string | Die Server-ID aus list_books. |
| current_page | integer | Aktuelle Seite; der Prozentwert wird daraus abgeleitet. |
| status | reading · backlog · finished | Regalwechsel, etwa finished beim Zuklappen. |
| mood | light · deep · short · escape · learn · work | Neue Stimmung. |
| note | string | Ersetzt die Notiz. |
| title | string | Korrektur. |
| author | string | Korrektur. |
AntwortDas aktualisierte Buch.
Entfernt ein Buch. Vorher den Nutzer fragen — wer ein Buch nur nicht mehr lesen will, meint meist update_book mit anderem Status.
| Parameter | Typ | Beschreibung |
|---|---|---|
| book_idPflicht | string | Die Server-ID aus list_books. |
AntwortBestätigung. Für den Agenten endgültig.