### Manual installation commands Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Clone the repository, install dependencies, and build the project. Required before running the server manually. ```bash # Clone the repository git clone https://github.com/8enSmith/mcp-open-library.git cd mcp-open-library # Install dependencies npm install # Build the project npm run build ``` -------------------------------- ### Example search_books input Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example input for the search_books tool, filtering by author and subject with sorting and limit. Demonstrates the accepted parameters. ```json { "author": "Ursula K. Le Guin", "subject": "fantasy", "sort": "old", "limit": 2 } ``` -------------------------------- ### Example search_books output Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example output from search_books showing a result with work key, best edition, and cover URL. Note that best_edition.edition_key is an OLID that can be passed to get_book_by_id. ```json { "num_found": 51, "offset": 0, "limit": 2, "results": [ { "title": "A Wizard of Earthsea", "authors": ["Ursula K. Le Guin"], "first_publish_year": 1968, "open_library_work_key": "/works/OL59798W", "edition_count": 87, "author_keys": ["OL31353A"], "best_edition": { "edition_key": "OL5613890M" }, "cover_url": "https://covers.openlibrary.org/b/id/13617691-M.jpg", "ratings_average": 3.95, "ebook_access": "borrowable" } ] } ``` -------------------------------- ### Add registry section to README.md Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Markdown section to insert under the '## Installation' heading, above '### Installing via Smithery'. It documents the MCP Registry listing and includes a curl command to inspect the published listing. ```markdown ### MCP Registry This server is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.8enSmith/mcp-open-library`. Clients that support the registry can install it by that name. To inspect the published listing: ```bash curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library" ``` ``` -------------------------------- ### run() Source: https://github.com/8ensmith/mcp-open-library Starts the MCP server by connecting to a stdio transport and registering a SIGINT listener. It resolves once the transport is connected and request handlers are answering. ```APIDOC ## run() ### Description Starts the MCP server by connecting to a stdio transport and registering a SIGINT listener. It resolves once the transport is connected and request handlers are answering. ### Method async run ### Signature ```ts async run(): Promise ``` ### Parameters No parameters. ### Behavior 1. Creates a `StdioServerTransport` and connects it to the server. 2. Registers a SIGINT listener that closes the server and exits the process. 3. Prints "Open Library MCP server running on stdio" to stderr. ### Throws - Any error from `server.connect()` on transport failure. ### Notes - Can only be called once per process because it owns the SIGINT listener. ``` -------------------------------- ### Set up development environment Source: https://github.com/8ensmith/mcp-open-library/blob/main/CONTRIBUTING.md Clone the repository, install dependencies, and set up the pre-commit hook. Requires Node.js version pinned in .nvmrc. The pre-commit hook runs ESLint, Prettier, and the full test suite. ```bash git clone https://github.com//mcp-open-library.git cd mcp-open-library nvm use # Node is pinned in .nvmrc npm install npx husky # installs the pre-commit hook ``` -------------------------------- ### Successful photo URL output Source: https://github.com/8ensmith/mcp-open-library Example plain-text URL returned when a photo exists. No isError flag is set. ```text https://covers.openlibrary.org/a/olid/OL26320A-L.jpg ``` -------------------------------- ### get_book_by_id input example Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example input for get_book_by_id using an OLID from a search result's best_edition.edition_key. Returns the full edition record including ISBN arrays. ```json { "idType": "olid", "idValue": "OL5613890M" } ``` -------------------------------- ### Run tests in watch mode with npm test Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Starts Vitest in watch mode for development. Use this when iterating on tests. ```bash npm test ``` -------------------------------- ### Example successful cover URL output Source: https://github.com/8ensmith/mcp-open-library Plain-text URL returned when a cover exists; no isError flag is set. ```text https://covers.openlibrary.org/b/isbn/9780547928227-L.jpg ``` -------------------------------- ### get_authors_by_name output Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example output from get_authors_by_name. Each result's 'key' can be passed to get_author_info for the full author record. 'alternate_names' is abridged here. ```json { "num_found": 2, "offset": 0, "limit": 2, "results": [ { "key": "OL26320A", "name": "J.R.R. Tolkien", "alternate_names": ["John Ronald Reuel Tolkien", "Tolkien"], "birth_date": "3 January 1892", "top_work": "The Hobbit", "work_count": 355 }, { "key": "OL332676A", "name": "J. R. R. Tolkien Centenary Conference (1992 Keble College, Oxford)", "top_work": "Proceedings of the J.R.R. Tolkien Centenary Conference, 1992", "work_count": 2 } ] } ``` -------------------------------- ### MCP client call example Source: https://github.com/8ensmith/mcp-open-library JSON payload for invoking the get_author_photo tool with an OLID. ```json { "olid": "OL26320A" } ``` -------------------------------- ### get_author_info output Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example output from get_author_info with full author details including name, birth/death dates, bio, alternate names, photos, remote IDs, and revision info. ```json { "name": "J. R. R. Tolkien", "personal_name": "John Ronald Reuel Tolkien", "birth_date": "3 January 1892", "death_date": "2 September 1973", "bio": "John Ronald Reuel Tolkien (1892-1973) was a major scholar of the English language, specializing in Old and Middle English. He served as the Rawlinson and Bosworth Professor of Anglo-Saxon and later the Merton Professor of English Language and Literature at Oxford University.", "alternate_names": ["John Ronald Reuel Tolkien"], "photos": [6791763], "key": "/authors/OL26320A", "remote_ids": { "viaf": "95218067", "wikidata": "Q892" }, "revision": 43, "last_modified": { "type": "/type/datetime", "value": "2023-02-12T05:50:22.881" } } ``` -------------------------------- ### Example response for tools/list (schema excerpt) Source: https://github.com/8ensmith/mcp-open-library Shows the MCP response shape for the tools/list method, with one tool entry (get_book_by_title) including inputSchema and annotations. The inputSchema is generated from Zod via toInputSchema, with the $schema key removed. All tools have readOnlyHint and openWorldHint set to true. ```json { "tools": [ { "name": "get_book_by_title", "title": "Find books by title", "description": "Search for a book by its title on Open Library. ...", "inputSchema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "The title of the book to search for." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } }, "required": ["title"] }, "annotations": { "readOnlyHint": true, "openWorldHint": true } } ] } ``` -------------------------------- ### Usage: gating server startup on isMainModule Source: https://github.com/8ensmith/mcp-open-library Shows how the server's main block uses isMainModule to start a stdio session only when the module is executed directly, preventing an import from starting the server. The comment references src/index.ts:96. ```TypeScript import { isMainModule } from "./utils/main-module.js"; import { OpenLibraryServer } from "./index.js"; // src/index.ts:96 if (isMainModule(import.meta.url)) { const server = new OpenLibraryServer(); server.run().catch(console.error); } ``` -------------------------------- ### Run a single Vitest test file or case Source: https://github.com/8ensmith/mcp-open-library/blob/main/CLAUDE.md Shows how to run one test file or a single test case by name. The -t flag filters by test name; the example uses a test in src/tools/get-book-by-id/index.test.ts. ```bash npx vitest run src/tools/get-book-by-id/index.test.ts npx vitest run -t "should return book details when given a valid OLID" ``` -------------------------------- ### get_book_by_title output Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example output from get_book_by_title showing a single result with book details, including authors, publication year, work key, edition count, cover URL, ratings, and ebook access. ```json { "num_found": 224, "offset": 0, "limit": 1, "results": [ { "title": "The Hobbit", "authors": ["J.R.R. Tolkien"], "first_publish_year": 1937, "open_library_work_key": "/works/OL27482W", "edition_count": 481, "author_keys": ["OL26320A"], "best_edition": { "edition_key": "OL51709286M", "isbn_13": "9780395520215", "isbn_10": "0395520215" }, "cover_url": "https://covers.openlibrary.org/b/id/14627509-M.jpg", "ratings_average": 4.29, "ebook_access": "borrowable" } ] } ``` -------------------------------- ### smithery.yaml Smithery deployment Source: https://github.com/8ensmith/mcp-open-library Smithery deployment manifest. The configSchema is an empty object, so Smithery users pass no configuration. The start command runs node build/index.js. ```yaml startCommand: type: stdio configSchema: type: object description: No configuration needed commandFunction: | (config) => ({ command: 'node', args: ['build/index.js'] }) exampleConfig: {} ``` -------------------------------- ### Example missing-cover message output Source: https://github.com/8ensmith/mcp-open-library Plain-text message returned when no cover exists; also no isError flag. ```text No cover image available for OLID OL00000000M. ``` -------------------------------- ### Missing photo message output Source: https://github.com/8ensmith/mcp-open-library Example message returned when no photo exists. Also no isError flag, as it is a valid negative answer. ```text No author photo available for OLID OL99999999A. ``` -------------------------------- ### Programmatic usage example Source: https://github.com/8ensmith/mcp-open-library Shows how to use the get_book_by_title tool programmatically, including argument validation and error handling. Empty title is rejected before any HTTP call, and errors are handled with InvalidArgumentsError. ```TypeScript import { handleGetBookByTitle } from "./tools/get-book-by-title/index.js"; import { InvalidArgumentsError, parseArgs } from "./utils/errors.js"; import { createOpenLibraryClients } from "./utils/http.js"; const clients = createOpenLibraryClients("1.2.6"); try { // Empty title is rejected before any HTTP call const args = parseArgs( (await import("./tools/get-book-by-title/index.js")).GetBookByTitleArgsSchema, { title: "" }, "get_book_by_title", ); } catch (error) { if (error instanceof InvalidArgumentsError) { console.error(error.message); // "Invalid arguments for get_book_by_title: title: Title cannot be empty" } } const result = await handleGetBookByTitle( { title: "Dune", limit: 3, offset: 0 }, clients, ); if (result.isError) { console.error("Lookup failed:", result.content[0].text); } else { console.log(result.content[0].text); // pretty-printed SearchResults JSON } ``` -------------------------------- ### get_book_by_id output Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Example output from get_book_by_id with detailed book information including title, authors, publishers, publication date, page count, ISBNs, OCLC, OLID, cover URL, and links. ```json { "title": "The Hobbit", "authors": [ "J. R. R. Tolkien" ], "publishers": [ "Houghton Mifflin Harcourt" ], "publish_date": "October 21, 2012", "number_of_pages": 300, "isbn_13": [ "9780547928227" ], "isbn_10": [ "054792822X" ], "oclc": [ "794607877" ], "olid": [ "OL25380781M" ], "open_library_edition_key": "/books/OL25380781M", "open_library_work_key": "/works/OL45883W", "cover_url": "https://covers.openlibrary.org/b/id/8231496-M.jpg", "info_url": "https://openlibrary.org/books/OL25380781M/The_Hobbit", "preview_url": "https://archive.org/details/hobbit00tolkien" } ``` -------------------------------- ### Converting a single raw doc with toBookInfo Source: https://github.com/8ensmith/mcp-open-library Demonstrates converting a single raw document using toBookInfo. The example shows the expected best_edition output with edition_key and isbn_13. ```TypeScript const info = toBookInfo({ title: "Dune", key: "/works/OL16124059W", editions: { docs: [{ key: "/books/OL7342018M", isbn: ["9780441172719"] }] }, }); console.log(info.best_edition); // { edition_key: "OL7342018M", isbn_13: "9780441172719" } ``` -------------------------------- ### Create validate-server-json.yml workflow Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md GitHub Actions workflow that validates server.json on pull requests. It runs tests, checks release consistency, installs mcp-publisher, and validates server.json. No tag argument is passed, so the checker skips tag comparison and asserts only file-to-file invariants. This job needs no id-token permission. ```yaml name: Validate server.json on: pull_request: paths: - server.json - package.json - scripts/** - .github/workflows/validate-server-json.yml jobs: validate: runs-on: ubuntu-latest permissions: contents: read steps: - name: Checkout code uses: actions/checkout@v5 - name: Set up Node.js uses: actions/setup-node@v5 with: node-version-file: .nvmrc - name: Install dependencies run: npm ci - name: Run tests run: npm run test:precommit - name: Assert release metadata is consistent run: node scripts/assert-release-consistency.mjs - name: Install mcp-publisher run: | curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher - name: Validate server.json run: ./mcp-publisher validate ``` -------------------------------- ### Usage example for result builders Source: https://github.com/8ensmith/mcp-open-library Shows how to build each kind of result the way the handlers do: a valid empty answer, a failure a model can read and correct, and a structured payload. ```TypeScript import { textResult, errorTextResult, jsonResult } from "./utils/results.js"; // Valid empty answer — no isError const empty = textResult('No books found matching title: "The Hobbit"'); console.log(empty.isError); // undefined / falsy // A failure a model can read and correct const failure = errorTextResult("Author with key \"OL99999A\" not found."); console.log(failure.isError); // true // A structured payload const data = jsonResult({ num_found: 0, offset: 0, limit: 10, results: [] }); console.log(data.content[0].type); // "text" console.log(data.content[0].text); // pretty-printed JSON ``` -------------------------------- ### Function createHttpClient Source: https://github.com/8ensmith/mcp-open-library Creates an Axios instance with a 15-second timeout and a User-Agent header naming the application. Open Library throttles unidentified clients to 1 request/second, while clients sending a User-Agent get 3/second. ```TypeScript export function createHttpClient( baseURL: string, version: string, ): AxiosInstance { return axios.create({ baseURL, timeout: REQUEST_TIMEOUT_MS, headers: { "User-Agent": `mcp-open-library/${version} (+https://github.com/8enSmith/mcp-open-library)`, }, }); } ``` -------------------------------- ### Example BookDetails JSON response Source: https://github.com/8ensmith/mcp-open-library Example return value from the get_book_by_id handler, showing the shape of a BookDetails object with fields like title, authors, ISBNs, and URLs. ```JSON { "title": "The Hobbit", "authors": ["J. R. R. Tolkien"], "publishers": ["Houghton Mifflin Harcourt"], "publish_date": "October 21, 2012", "number_of_pages": 300, "isbn_13": ["9780547928227"], "isbn_10": ["054792822X"], "oclc": ["794607877"], "olid": ["OL25380781M"], "open_library_edition_key": "/books/OL25380781M", "open_library_work_key": "/works/OL45883W", "cover_url": "https://covers.openlibrary.org/b/id/8231496-M.jpg", "info_url": "https://openlibrary.org/books/OL25380781M/The_Hobbit", "preview_url": "https://archive.org/details/hobbit00tolkien" } ``` -------------------------------- ### Build and run MCP Inspector Source: https://github.com/8ensmith/mcp-open-library/blob/main/CONTRIBUTING.md Build the server and open it in the MCP Inspector to test changes in a real client. ```bash npm run build npm run inspector ``` -------------------------------- ### OpenLibraryServer run() method signature Source: https://github.com/8ensmith/mcp-open-library Async method that connects the stdio transport, registers a SIGINT listener, and prints a startup message. Can only be called once per process because it owns the SIGINT handler. ```typescript async run(): Promise ``` -------------------------------- ### Cut the release with npm version patch and push Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Run `npm version patch` to bump the version and trigger the `version` lifecycle hook, which promotes the changelog. Then push with `--follow-tags` to publish the tag-triggered workflow. ```bash npm version patch git push --follow-tags ``` -------------------------------- ### Run vitest to verify test fails Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Command to run the test file. Expected to fail because the implementation file ./assert-release-consistency.mjs cannot be resolved. ```bash npx vitest run scripts/assert-release-consistency.test.mjs ``` -------------------------------- ### Trigger a release with npm version and push Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Run `npm version patch` (or minor/major) to bump the version, update server.json, and promote the changelog's `## [Unreleased]` heading. Requires a clean working tree and a pre-existing `## [Unreleased]` heading in CHANGELOG.md; the pre-commit hook runs lint and the full test suite. Then push with `git push --follow-tags` to trigger the automated publish workflow. ```bash npm version patch # or minor / major git push --follow-tags ``` -------------------------------- ### Create server.json Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md JSON configuration for the MCP server registry listing. Version 1.0.2 matches package.json. Tasks 3, 5, and 6 read this file. ```json { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.8enSmith/mcp-open-library", "title": "Open Library", "description": "Search books and authors on the Internet Archive's Open Library", "version": "1.0.2", "websiteUrl": "https://github.com/8enSmith/mcp-open-library#readme", "repository": { "url": "https://github.com/8enSmith/mcp-open-library", "source": "github" }, "packages": [ { "registryType": "npm", "identifier": "mcp-open-library", "version": "1.0.2", "transport": { "type": "stdio" } } ] } ``` -------------------------------- ### Verify full suite and lint Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Runs build, lint, and precommit tests. The build step matters because vitest also picks up compiled tests under build/, so a stale build/ would run old assertions. ```bash npm run build && npm run lint && npm run test:precommit ``` -------------------------------- ### GET /search/authors.json Source: https://github.com/8ensmith/mcp-open-library Search for authors by name in the Open Library catalog. Returns a list of author documents matching the search query. ```APIDOC ## [GET] /search/authors.json ### Description Search for authors by name in the Open Library catalog. Returns a list of author documents matching the search query. ### Method GET ### Endpoint https://openlibrary.org/search/authors.json ### Parameters #### Query Parameters - **q** (string) - Required - The author name to search for - **limit** (int) - Optional - Maximum number of results - **offset** (int) - Optional - Number of results to skip ### Response #### Success Response (200) - **numFound** (int) - Number of results found - **start** (int) - Starting index of results - **numFoundExact** (bool) - Whether the search was exact - **docs** (array) - List of author documents ``` -------------------------------- ### Import and run OpenLibraryServer Source: https://github.com/8ensmith/mcp-open-library Import the OpenLibraryServer class and run it, blocking on the stdio transport. Importing the class does not auto-start the server; only the entry script auto-runs. ```ts import { OpenLibraryServer } from "mcp-open-library"; // resolves build/index.js const server = new OpenLibraryServer(); await server.run(); // blocks on the stdio transport ``` -------------------------------- ### server.json configuration Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/specs/2026-08-08-mcp-registry-publishing-design.md New server.json at repo root defining the MCP server metadata for the Open Library server. The schema caps description at 100 characters; this description is 62. No environmentVariables or packageArguments are included because the server takes no configuration. ```json { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.8enSmith/mcp-open-library", "title": "Open Library", "description": "Search books and authors on the Internet Archive's Open Library", "version": "1.0.3", "websiteUrl": "https://github.com/8enSmith/mcp-open-library#readme", "repository": { "url": "https://github.com/8enSmith/mcp-open-library", "source": "github" }, "packages": [ { "registryType": "npm", "identifier": "mcp-open-library", "version": "1.0.3", "transport": { "type": "stdio" } } ] } ``` -------------------------------- ### get_author_info Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Get detailed information for a specific author using their Open Library Author Key. Returns author details such as biography, birth date, and links. ```APIDOC ## get_author_info ### Description Get detailed information for a specific author using their Open Library Author Key. Returns author details such as biography, birth date, and links. ### Parameters - `authorKey` (string) - Required - The Open Library Author Key (e.g., `OL31353A`). ``` -------------------------------- ### Verify docs render Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Command to run markdownlint on README.md and CHANGELOG.md. Expected: no errors introduced by the new sections. Pre-existing warnings elsewhere are not this task's concern. ```bash npx --yes markdownlint-cli2 README.md CHANGELOG.md 2>&1 | tail -20 || true ``` -------------------------------- ### Run version test to verify failure Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Runs the new test expecting failure with 'expected '1.0.0' to be '1.0.2''. This failure reproduces the version drift. ```bash npx vitest run src/index.test.ts -t "reports the version from package.json" ``` -------------------------------- ### MCP client call for ISBN cover Source: https://github.com/8ensmith/mcp-open-library Example JSON payload for an MCP client call requesting a large cover by ISBN. ```json { "key": "ISBN", "value": "9780547928227", "size": "L" } ``` -------------------------------- ### Run tests once with npm run test:precommit Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Runs the test suite once and exits, as used by the pre-commit hook and CI. ```bash npm run test:precommit ``` -------------------------------- ### List version tags to confirm workflow cannot fire Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Lists existing version tags. Expected output is only v1.0.0, v1.0.1, v1.0.2; no new tag exists, so merging the workflow publishes nothing. ```bash git tag --list 'v*' ``` -------------------------------- ### get_book_by_id Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Get detailed book information using a specific identifier (ISBN, LCCN, OCLC, or OLID). Returns the full edition record including ISBN arrays. ```APIDOC ## get_book_by_id ### Description Get detailed book information using a specific identifier (ISBN, LCCN, OCLC, or OLID). Returns the full edition record including ISBN arrays. ### Parameters - `idType` (string) - Required - The type of identifier: `isbn`, `lccn`, `oclc`, or `olid`. - `idValue` (string) - Required - The identifier value. ### Request Example ```json { "idType": "olid", "idValue": "OL5613890M" } ``` ``` -------------------------------- ### Docker build, run, and Inspector commands Source: https://github.com/8ensmith/mcp-open-library Build and run the Docker image, then connect the MCP Inspector over HTTP on port 8080. The image runs the stdio server wrapped in mcp-proxy (v2.10.6) for HTTP/SSE access. ```bash docker build -t mcp-open-library . docker run -p 8080:8080 mcp-open-library npm run inspector http://localhost:8080 # connect the Inspector over HTTP ``` -------------------------------- ### get_book_cover Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Get the URL for a book's cover image using a specific identifier (ISBN, OCLC, LCCN, OLID, or ID). Returns the cover image URL. ```APIDOC ## get_book_cover ### Description Get the URL for a book's cover image using a specific identifier (ISBN, OCLC, LCCN, OLID, or ID). Returns the cover image URL. ### Parameters - `idType` (string) - Required - The type of identifier: `isbn`, `oclc`, `lccn`, `olid`, or `id`. - `idValue` (string) - Required - The identifier value. ``` -------------------------------- ### Run consistency checker against real files Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Command to run the release consistency checker. Expected output: 'Release metadata is consistent.' and exit code 0. ```bash node scripts/assert-release-consistency.mjs ``` -------------------------------- ### Add pkg constant before OpenLibraryServer class Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Adds a constant that reads package.json version using import.meta.url. This resolves to the repo root from src/index.ts under vitest and to the package root from build/index.js at runtime. ```ts const pkg = JSON.parse( readFileSync(new URL("../package.json", import.meta.url), "utf8"), ) as { version: string }; ``` -------------------------------- ### MCP client call with ISBN (case-insensitive) Source: https://github.com/8ensmith/mcp-open-library Example request payload using an ISBN. The idType is normalised before the enum check, so 'ISBN' is accepted. ```json { "idType": "ISBN", "idValue": "9780547928227" } ``` -------------------------------- ### Verify npm package and registry search Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/specs/2026-08-08-mcp-registry-publishing-design.md Commands to verify the published package and registry search after release. Run after `npm version patch` and `git push --follow-tags`. ```bash npm view mcp-open-library@1.0.3 mcpName curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library" ``` -------------------------------- ### GET /authors/{key}.json Source: https://github.com/8ensmith/mcp-open-library Retrieve detailed information about a specific author using their Open Library key. Returns author details including bio information. ```APIDOC ## [GET] /authors/{key}.json ### Description Retrieve detailed information about a specific author using their Open Library key. Returns author details including bio information. ### Method GET ### Endpoint https://openlibrary.org/authors/{key}.json ### Parameters #### Path Parameters - **key** (string) - Required - The author's Open Library key (e.g. `OL26320A`) ### Response #### Success Response (200) - Returns detailed author information with `bio` object flattened to string #### Error Response (404) - Returns `Author with key "…" not found.` error result ``` -------------------------------- ### GET /search.json Source: https://github.com/8ensmith/mcp-open-library Search books in the Open Library catalog using a free-form Solr query or specific criteria. Returns a list of book documents matching the search parameters. ```APIDOC ## [GET] /search.json ### Description Search books in the Open Library catalog using a free-form Solr query or specific criteria. Returns a list of book documents matching the search parameters. ### Method GET ### Endpoint https://openlibrary.org/search.json ### Parameters #### Query Parameters - **fields** (string) - Required - Always `SEARCH_FIELDS` - **limit** (int 1–50) - Optional - default 10 - **offset** (int 0–1000) - Optional - default 0 - **q** (string) - Optional - free-form Solr query - **title** (string) - Optional - title criteria - **author** (string) - Optional - author criteria - **subject** (string) - Optional - subject criteria - **place** (string) - Optional - place criteria - **person** (string) - Optional - person criteria - **publisher** (string) - Optional - publisher criteria - **isbn** (string) - Optional - ISBN criteria - **language** (string `^[a-z]{3}$`) - Optional - language code - **sort** (one of `new|old|random|key|rating|readinglog|want_to_read|currently_reading|already_read|title`) - Optional - sort order ### Response #### Success Response (200) - **numFound** (int) - Number of results found - **docs** (array) - List of book documents Returns 200 even when `docs` is empty (yields a `No books found…` text result). ``` -------------------------------- ### Vitest test for checkReleaseConsistency Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Tests the checkReleaseConsistency function from ./assert-release-consistency.mjs. Verifies that it returns no problems when package.json, server.json, and git tag agree, and reports specific problems for mismatches in tag, server.json version, packages[0].version, packages[0].identifier, name/mcpName, and missing packages entry. Also checks that all problems are reported at once. The test file is expected to fail initially because the implementation file does not exist yet. ```javascript import { describe, it, expect } from "vitest"; import { checkReleaseConsistency } from "./assert-release-consistency.mjs"; const pkg = { name: "mcp-open-library", version: "1.0.3", mcpName: "io.github.8enSmith/mcp-open-library", }; const server = { name: "io.github.8enSmith/mcp-open-library", version: "1.0.3", packages: [{ identifier: "mcp-open-library", version: "1.0.3" }], }; describe("checkReleaseConsistency", () => { it("returns no problems when everything agrees", () => { expect(checkReleaseConsistency({ pkg, server, tag: "v1.0.3" })).toEqual([]); }); it("skips the tag check when no tag is supplied", () => { expect(checkReleaseConsistency({ pkg, server })).toEqual([]); }); it("accepts a tag without the v prefix", () => { expect(checkReleaseConsistency({ pkg, server, tag: "1.0.3" })).toEqual([]); }); it("reports a tag that does not match package.json", () => { const problems = checkReleaseConsistency({ pkg, server, tag: "v9.9.9" }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("git tag"); }); it("reports a server.json version mismatch", () => { const problems = checkReleaseConsistency({ pkg, server: { ...server, version: "1.0.2" }, tag: "v1.0.3", }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("server.json version"); }); it("reports a packages[0].version mismatch", () => { const problems = checkReleaseConsistency({ pkg, server: { ...server, packages: [{ identifier: "mcp-open-library", version: "1.0.2" }], }, tag: "v1.0.3", }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("packages[0].version"); }); it("reports a packages[0].identifier mismatch", () => { const problems = checkReleaseConsistency({ pkg, server: { ...server, packages: [{ identifier: "wrong-package", version: "1.0.3" }], }, tag: "v1.0.3", }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("packages[0].identifier"); }); it("reports a name/mcpName mismatch", () => { const problems = checkReleaseConsistency({ pkg, server: { ...server, name: "io.github.8enSmith/wrong-name" }, tag: "v1.0.3", }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("mcpName"); }); it("reports a missing packages entry", () => { const problems = checkReleaseConsistency({ pkg, server: { ...server, packages: [] }, tag: "v1.0.3", }); expect(problems).toHaveLength(1); expect(problems[0]).toContain("packages[0]"); }); it("reports every problem at once rather than stopping at the first", () => { const problems = checkReleaseConsistency({ pkg, server: { name: "io.github.8enSmith/wrong-name", version: "1.0.1", packages: [{ identifier: "wrong-package", version: "1.0.2" }], }, tag: "v9.9.9", }); expect(problems).toHaveLength(5); }); }); ``` -------------------------------- ### MCP client call for internal cover ID Source: https://github.com/8ensmith/mcp-open-library Example JSON payload for an MCP client call requesting a small cover by internal cover ID. ```json { "key": "ID", "value": "8231496", "size": "S" } ``` -------------------------------- ### GET /api/volumes/brief/{idType}/{idValue}.json Source: https://github.com/8ensmith/mcp-open-library Retrieve book details by a specific identifier such as ISBN, LCCN, OCLC, or OLID. Returns detailed book information including records and items. ```APIDOC ## [GET] /api/volumes/brief/{idType}/{idValue}.json ### Description Retrieve book details by a specific identifier such as ISBN, LCCN, OCLC, or OLID. Returns detailed book information including records and items. ### Method GET ### Endpoint https://openlibrary.org/api/volumes/brief/{idType}/{idValue}.json ### Parameters #### Path Parameters - **idType** (string) - Required - One of `isbn|lccn|oclc|olid` (lowercased before the request) - **idValue** (string) - Required - The identifier value (e.g. `9780547928227`) ### Response #### Success Response (200) - **records** (object) - Record of book records - **items** (array) - List of items #### Error Response (404) - Returns `No book found for …` error result #### Error Response (200 with empty records) - Returns `No book found for …` error result ``` -------------------------------- ### Pre-flight namespace check with mcp-publisher login and token inspection Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Run before releasing to confirm the registry grants the expected namespace. Expect a permissions claim covering `io.github.8enSmith/*` (capital S). If a different case appears, correct `server.json` `name` and `package.json` `mcpName` together. ```bash mcp-publisher login github node -e "const t=require(require('os').homedir()+'/.config/mcp-publisher/token.json').token; console.log(JSON.parse(Buffer.from(t.split('.')[1],'base64url')))" ``` -------------------------------- ### Add version test to OpenLibraryServer describe block Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Adds a test that verifies the server reports the version from package.json. beforeEach clears mocks and constructs a fresh OpenLibraryServer, so mock.calls[0] is that construction's arguments. ```ts it("reports the version from package.json", () => { const pkg = JSON.parse( readFileSync(new URL("../package.json", import.meta.url), "utf8"), ) as { version: string }; const [implementation] = (Server as any).mock.calls[0]; expect(implementation.version).toBe(pkg.version); expect(implementation.name).toBe("open-library-server"); }); ``` -------------------------------- ### Implementation of syncServerJson (sync-server-json.mjs) Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Node.js module that updates the version in server.json for the matching npm package entry. Throws if the server name does not match mcpName. When run directly, reads package.json and server.json, syncs, and writes back with a log message. ```javascript import { readFileSync, writeFileSync } from "node:fs"; export function syncServerJson(server, { version, mcpName, packageName }) { if (server.name !== mcpName) { throw new Error( `server.json name "${server.name}" does not match package.json mcpName "${mcpName}". ` + "The server name is permanent and must be corrected by hand.", ); } return { ...server, version, packages: server.packages.map((entry) => entry.identifier === packageName ? { ...entry, version } : entry, ), }; } if (process.argv[1] === new URL(import.meta.url).pathname) { const serverUrl = new URL("../server.json", import.meta.url); const pkg = JSON.parse( readFileSync(new URL("../package.json", import.meta.url), "utf8"), ); const server = JSON.parse(readFileSync(serverUrl, "utf8")); const updated = syncServerJson(server, { version: pkg.version, mcpName: pkg.mcpName, packageName: pkg.name, }); writeFileSync(serverUrl, `${JSON.stringify(updated, null, 2)}\n`); console.log(`server.json synced to ${pkg.version}`); } ``` -------------------------------- ### Test for syncServerJson (sync-server-json.test.mjs) Source: https://github.com/8ensmith/mcp-open-library/blob/main/docs/superpowers/plans/2026-08-08-publish-to-mcp-registry.md Vitest test suite for the syncServerJson function. Covers updating top-level and package versions, preserving unrelated fields, immutability, and throwing on name mismatch. Run with `npx vitest run scripts/sync-server-json.test.mjs`; initially fails because the module is missing. ```javascript import { describe, it, expect } from "vitest"; import { syncServerJson } from "./sync-server-json.mjs"; const mcpName = "io.github.8enSmith/mcp-open-library"; const packageName = "mcp-open-library"; function makeServer() { return { $schema: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", name: mcpName, title: "Open Library", description: "Search books and authors on the Internet Archive's Open Library", version: "1.0.2", websiteUrl: "https://github.com/8enSmith/mcp-open-library#readme", repository: { url: "https://github.com/8enSmith/mcp-open-library", source: "github", }, packages: [ { registryType: "npm", identifier: packageName, version: "1.0.2", transport: { type: "stdio" }, }, ], }; } describe("syncServerJson", () => { it("updates the top-level version", () => { const result = syncServerJson(makeServer(), { version: "1.0.3", mcpName, packageName, }); expect(result.version).toBe("1.0.3"); }); it("updates the matching package entry version", () => { const result = syncServerJson(makeServer(), { version: "1.0.3", mcpName, packageName, }); expect(result.packages[0].version).toBe("1.0.3"); }); it("leaves package entries for other registries untouched", () => { const server = makeServer(); server.packages.push({ registryType: "nuget", identifier: "Someone.Else", version: "9.9.9", transport: { type: "stdio" }, }); const result = syncServerJson(server, { version: "1.0.3", mcpName, packageName, }); expect(result.packages[1].version).toBe("9.9.9"); }); it("preserves every unrelated field", () => { const server = makeServer(); const result = syncServerJson(server, { version: "1.0.3", mcpName, packageName, }); expect(result.$schema).toBe(server.$schema); expect(result.name).toBe(mcpName); expect(result.title).toBe("Open Library"); expect(result.description).toBe(server.description); expect(result.websiteUrl).toBe(server.websiteUrl); expect(result.repository).toEqual(server.repository); expect(result.packages[0].registryType).toBe("npm"); expect(result.packages[0].transport).toEqual({ type: "stdio" }); }); it("does not mutate the input", () => { const server = makeServer(); syncServerJson(server, { version: "1.0.3", mcpName, packageName }); expect(server.version).toBe("1.0.2"); expect(server.packages[0].version).toBe("1.0.2"); }); it("throws when the server name does not match mcpName", () => { expect(() => syncServerJson(makeServer(), { version: "1.0.3", mcpName: "io.github.8enSmith/something-else", packageName, }), ).toThrow(/does not match/); }); }); ``` -------------------------------- ### Docker build and run commands Source: https://github.com/8ensmith/mcp-open-library/blob/main/README.md Commands to build and run the MCP server using Docker. The server is exposed on port 8080. ```bash docker build -t mcp-open-library . docker run -p 8080:8080 mcp-open-library ``` -------------------------------- ### MCP client call with OLID Source: https://github.com/8ensmith/mcp-open-library Example request payload for the get-book-by-id tool using an Open Library ID (OLID). The idType is 'olid' and idValue is the edition key from a search hit. ```json { "idType": "olid", "idValue": "OL5613890M" } ```