Reference
Bookheap speaks MCP: the tools an agent uses to read and tend the library. The binding contract remains agents.md — this page is its detailed reference.
https://mcp.prod.bookheap.app/mcpA 401 with WWW-Authenticate is the front door, not an error: it drives OAuth discovery (RFC 9728, then RFC 8414, then RFC 7591).
The agent signs in through the same OAuth dialog as the human and receives a time-limited token with exactly the approved rights. Reading and writing are separate: books/read answers questions, books/write adds and edits. An agent that only answers needs no write scope.
Lists the library's books, filterable by shelf and mood. Answers “what am I reading?” and “what is on my bookshelf?” in one call.
| Parameter | Type | Description |
|---|---|---|
| status | reading · backlog · finished | Filter by shelf: reading (Now), backlog (Next), finished (Done). |
| mood | light · deep · short · escape · learn · work | Filter by mood. |
ReturnsAll matching books, complete and without cursors.
Fetches one book by id, including reading progress. Ids come from list_books; they are opaque server ids and are never shown to the user.
| Parameter | Type | Description |
|---|---|---|
| book_idrequired | string | The server id from list_books. |
ReturnsThe book with all fields.
Searches the public catalogue (Open Library) by title, author or ISBN. Call before add_book so the right edition arrives with page count and cover.
| Parameter | Type | Description |
|---|---|---|
| queryrequired | string | A title, an author, or an ISBN. |
| limit | integer · 1–10 | How many candidates. Five is usually enough to find the right edition. |
ReturnsCandidates with title, author, year, page count and cover.
Adds one book. Defaults to the Next shelf (backlog) — where a recommendation belongs. Pass status reading only when the user has already started.
| Parameter | Type | Description |
|---|---|---|
| titlerequired | string | The one required field. |
| author | string | Free text. |
| status | reading · backlog · finished | Defaults to backlog. |
| mood | light · deep · short · escape · learn · work | One of the six fixed moods. |
| note | string | Provenance and occasion — what the user will search for later. |
| page_count | integer | Page count of the edition; the percentage is derived from it. |
ReturnsThe created book including its bookId.
Adds many books in one call — for Goodreads or StoryGraph exports, typed lists, shelf photos. Deduplication is the agent's job.
| Parameter | Type | Description |
|---|---|---|
| booksrequired | array‹object› · max 100 | Up to 100 normalized records with add_book's fields; split larger imports. |
ReturnsA per-record result.
Changes a book: progress, shelf, mood, note, or a correction to title and author. Only the fields you pass change.
| Parameter | Type | Description |
|---|---|---|
| book_idrequired | string | The server id from list_books. |
| current_page | integer | Current page; the percentage is derived from it. |
| status | reading · backlog · finished | Shelf move, e.g. finished on closing the book. |
| mood | light · deep · short · escape · learn · work | New mood. |
| note | string | Replaces the note. |
| title | string | Correction. |
| author | string | Correction. |
ReturnsThe updated book.
Removes a book. Ask the user first — someone who merely stopped reading usually means update_book with a different status.
| Parameter | Type | Description |
|---|---|---|
| book_idrequired | string | The server id from list_books. |
ReturnsConfirmation. Final as far as the agent is concerned.