gutenberg-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 32, 'minimum': 1, 'description': 'Number of books to return (1â\x80\x9332). Default 20 gives a useful overview without overwhelming context.'}, 'topic': {'type': 'string', 'description': 'Filter by a subject or bookshelf keyword (case-insensitive phrase match). Example: "science fiction", "adventure", "detective". Applies on top of the language filter.'}, 'languages': {'type': 'array', 'items': {'type': 'string', 'maxLength': 2, 'minLength': 2}, 'description': 'Restrict to books in these languages (two-character ISO 639-1 codes). Example: ["en"] for English only, ["de", "fr"] for German or French. Omit for all languages.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['books', 'totalInCatalog', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'books': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'title', 'authors', 'languages', 'download_count', 'has_plain_text'], 'properties': {'id': {'type': 'number', 'description': 'Gutenberg ID.'}, 'title': {'type': 'string', 'description': 'Book title.'}, 'authors': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'birth_year', 'death_year'], 'properties': {'name': {'type': 'string', 'description': 'Author name in "Last, First" format.'}, 'birth_year': {'type': ['number', 'null'], 'description': 'Birth year, or null if unknown.'}, 'death_year': {'type': ['number', 'null'], 'description': 'Death year, or null if unknown or still living.'}}, 'description': 'Author entry.', 'additionalProperties': False}, 'description': 'Author(s).'}, 'languages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Language codes.'}, 'download_count': {'type': 'number', 'description': 'Total downloads â\x80\x94 the basis for the popularity ranking.'}, 'has_plain_text': {'type': 'boolean', 'description': 'True if media_type is "Text" AND a UTF-8 text/plain format is available via gutenberg_get_text.'}}, 'description': 'Book entry.', 'additionalProperties': False}, 'description': 'Top books by download count, most popular first.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_results', 'catalog_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_results`: No books match the language/topic filter combination. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one browse. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of books returned in this response.'}, 'truncated': {'type': 'boolean', 'description': 'True when the catalog held more matches than were returned.'}, 'totalInCatalog': {'type': 'number', 'description': 'Total books matching the filter in the full catalog (useful for context â\x80\x94 "top 20 of 60,000").'}, 'truncationCeiling': {'type': 'number', 'description': 'Download count of the least-popular book shown â\x80\x94 omitted books have at most this many downloads.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['id'], 'properties': {'id': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Project Gutenberg book ID. Visible in Gutenberg URLs (e.g., gutenberg.org/ebooks/1342) and returned by gutenberg_search_books and gutenberg_browse_popular. Example: 1342 for Pride and Prejudice, 2600 for War and Peace.', 'exclusiveMinimum': 0}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['id', 'title', 'authors', 'translators', 'editors', 'subjects', 'bookshelves', 'languages', 'copyright', 'media_type', 'download_count', 'summary', 'summaries', 'formats', 'has_plain_text']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'id': {'type': 'number', 'description': 'Gutenberg ID.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'catalog_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: No book exists with the given ID. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one lookup. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'title': {'type': 'string', 'description': 'Book title.'}, 'authors': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'birth_year', 'death_year'], 'properties': {'name': {'type': 'string', 'description': 'Author name in "Last, First" format.'}, 'birth_year': {'type': ['number', 'null'], 'description': 'Birth year, or null if unknown.'}, 'death_year': {'type': ['number', 'null'], 'description': 'Death year, or null if unknown or still living.'}}, 'description': 'Author entry.', 'additionalProperties': False}, 'description': 'Primary author(s).'}, 'editors': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'birth_year', 'death_year'], 'properties': {'name': {'type': 'string', 'description': 'Editor name.'}, 'birth_year': {'type': ['number', 'null'], 'description': 'Birth year, or null if unknown.'}, 'death_year': {'type': ['number', 'null'], 'description': 'Death year, or null if unknown.'}}, 'description': 'Editor entry.', 'additionalProperties': False}, 'description': 'Editors, if any.'}, 'formats': {'type': 'object', 'description': 'Map of MIME type to download URL. Key types: "text/plain; charset=utf-8" (preferred for gutenberg_get_text), "text/html", "application/epub+zip", "image/jpeg" (cover). Not every format is present for every book.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'string'}}, 'summary': {'type': ['string', 'null'], 'description': 'First entry of summaries â\x80\x94 the primary auto-generated summary of the work, or null when Gutendex has none.'}, 'subjects': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Library of Congress subject headings.'}, 'copyright': {'type': ['boolean', 'null'], 'description': 'Copyright status: false = public domain in the USA, true = under copyright, null = unknown.'}, 'languages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Two-character language codes for this edition.'}, 'summaries': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Every summary Gutendex holds for this work, in upstream order. Usually one; some records carry a long and a short variant. Empty when there are none.'}, 'media_type': {'type': 'string', 'description': '"Text" for readable books, "Sound" for audio books. Only "Text" books have plain-text content available for gutenberg_get_text.'}, 'bookshelves': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Project Gutenberg bookshelf categories (e.g., "Best Books Ever Listings", "Category: Classics of Literature").'}, 'translators': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'birth_year', 'death_year'], 'properties': {'name': {'type': 'string', 'description': 'Translator name.'}, 'birth_year': {'type': ['number', 'null'], 'description': 'Birth year, or null if unknown.'}, 'death_year': {'type': ['number', 'null'], 'description': 'Death year, or null if unknown.'}}, 'description': 'Translator entry.', 'additionalProperties': False}, 'description': 'Translators, if this is a translated work.'}, 'download_count': {'type': 'number', 'description': 'Total downloads â\x80\x94 popularity signal.'}, 'has_plain_text': {'type': 'boolean', 'description': 'True if media_type is "Text" AND a UTF-8 text/plain format ("text/plain; charset=utf-8") is present in formats â\x80\x94 prerequisite for gutenberg_get_text.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['id'], 'properties': {'id': {'type': 'integer', 'maximum': 9007199254740991, 'description': 'Project Gutenberg book ID. Use gutenberg_search_books or gutenberg_get_book to find IDs. Example: 1342 for Pride and Prejudice, 2600 for War and Peace, 84 for Frankenstein.', 'exclusiveMinimum': 0}, 'limit': {'type': 'integer', 'default': 20000, 'maximum': 50000, 'minimum': 1, 'description': 'Maximum number of characters to return in this chunk. Default 20,000 (~4â\x80\x935 pages of prose). Increase toward 50,000 for large context windows. The actual returned length may be slightly less than limit when a natural paragraph boundary is found within 500 characters of the limit â\x80\x94 check the length field in the response for the actual character count returned.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Character offset into the stripped literary text at which to start reading. 0 returns the beginning of the work. To read subsequent chunks, use offset = prior_offset + prior_length (the length field from the previous response â\x80\x94 NOT offset + limit, because the actual returned length may be slightly less than limit due to paragraph-boundary trimming).'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['id', 'title', 'text', 'offset', 'length', 'totalChars', 'remainingChars', 'hasMore', 'provenance', 'sourceFormat']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'id': {'type': 'number', 'description': 'Gutenberg book ID.'}, 'text': {'type': 'string', 'description': 'The requested chunk of literary text, stripped of Gutenberg license boilerplate. Encoding: UTF-8. Line endings: normalized to LF.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'audio_book', 'no_text_format', 'offset_out_of_range', 'text_fetch_failed', 'catalog_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: No book exists with the given ID. `audio_book`: The book is an audio recording (media_type "Sound"), not a text book â\x80\x94 no literary plain text is available. `no_text_format`: The book has no UTF-8 plain-text or HTML edition available to read (for example an older ASCII-only entry). `offset_out_of_range`: The offset is greater than or equal to totalChars (past the end of the book). `text_fetch_failed`: The Gutenberg file server returned an error or did not respond within the timeout. `catalog_unavailable`: The catalog lookup that precedes reading a book did not answer within the time this server allows. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'title': {'type': 'string', 'description': 'Book title, from the catalog record.'}, 'length': {'type': 'number', 'description': 'Number of characters in this chunk.'}, 'offset': {'type': 'number', 'description': 'Character offset where this chunk begins.'}, 'hasMore': {'type': 'boolean', 'description': 'True if there is more text after this chunk. When true, call again with offset = offset + length.'}, 'provenance': {'type': 'string', 'description': 'One-line source note with Project Gutenberg ID, title, and license URL.'}, 'totalChars': {'type': 'number', 'description': 'Total characters in the stripped literary text. Use with offset and length to determine progress and plan subsequent calls.'}, 'sourceFormat': {'enum': ['text/plain; charset=utf-8', 'text/plain; charset=us-ascii', 'text/html'], 'type': 'string', 'description': 'The format that was fetched. "text/html" indicates HTML-to-text conversion was applied because no plain-text format was available.'}, 'remainingChars': {'type': 'number', 'description': 'Characters remaining after this chunk (totalChars - offset - length). 0 means this chunk includes the end of the book.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'ids': {'type': 'array', 'items': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}, 'description': 'Narrow results to specific Gutenberg ID numbers. Other filters still apply. Useful for batch pre-fetching known IDs; use gutenberg_get_book for single-ID lookups.'}, 'page': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'description': 'Page number for paginated results (1-indexed). Each page returns up to 32 books. Use totalCount to determine total pages.', 'exclusiveMinimum': 0}, 'sort': {'enum': ['popular', 'ascending', 'descending'], 'type': 'string', 'default': 'popular', 'description': 'Result ordering. "popular" (default) sorts by download count descending. "ascending" and "descending" sort by Gutenberg ID number.'}, 'query': {'type': 'string', 'description': 'Words to match against book titles and author names (case-insensitive, space-separated). Example: "dickens expectations" matches Great Expectations by Charles Dickens.'}, 'topic': {'type': 'string', 'description': 'Case-insensitive phrase to match against subjects and bookshelves. Example: "detective" returns books on the "Detective and Mystery Stories" bookshelf. Separate from query â\x80\x94 topic searches categorization metadata, not title/author.'}, 'languages': {'type': 'array', 'items': {'type': 'string', 'maxLength': 2, 'minLength': 2}, 'description': 'Filter to books in any of these two-character ISO 639-1 language codes. Example: ["en"] for English, ["fr", "de"] for French or German.'}, 'author_year_end': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Include only books with at least one author alive on or before this year. Example: author_year_start=1800 with author_year_end=1899 returns books with 19th-century authors.'}, 'author_year_start': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Include only books with at least one author alive on or after this year (positive = CE, negative = BCE). Combine with author_year_end for a range.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['books', 'totalCount', 'page', 'hasMore']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'page': {'type': 'number', 'description': 'Current page number.'}, 'books': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'title', 'authors', 'languages', 'subjects', 'download_count', 'has_plain_text'], 'properties': {'id': {'type': 'number', 'description': 'Gutenberg ID â\x80\x94 pass to gutenberg_get_book for the full record or gutenberg_get_text to read the book.'}, 'title': {'type': 'string', 'description': 'Book title.'}, 'authors': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'birth_year', 'death_year'], 'properties': {'name': {'type': 'string', 'description': 'Author name in "Last, First" format.'}, 'birth_year': {'type': ['number', 'null'], 'description': 'Author birth year, or null if unknown.'}, 'death_year': {'type': ['number', 'null'], 'description': 'Author death year, or null if unknown or still living.'}}, 'description': 'Author entry.', 'additionalProperties': False}, 'description': 'Author(s) of the work.'}, 'subjects': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Library of Congress subject headings.'}, 'languages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Two-character language codes for this edition.'}, 'download_count': {'type': 'number', 'description': 'Total downloads from Project Gutenberg â\x80\x94 a real popularity signal reflecting actual reader interest.'}, 'has_plain_text': {'type': 'boolean', 'description': 'True if the book has media_type "Text" AND a UTF-8 text/plain format available â\x80\x94 prerequisite for gutenberg_get_text.'}}, 'description': 'Book entry.', 'additionalProperties': False}, 'description': 'Matching books, ordered by the sort parameter.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_results', 'page_out_of_range', 'catalog_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_results`: The query matched no books in the catalog. `page_out_of_range`: The requested page number is past the last page of results for this query. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one search. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'hasMore': {'type': 'boolean', 'description': 'True if there are additional pages of results.'}, 'totalCount': {'type': 'number', 'description': 'Total number of books matching the query across all pages.'}}, 'additionalProperties': False}