mcp-open-library: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

nvm use                  # Node is pinned in .nvmrc (v22.21.1)
npm run build            # tsc -> build/, then chmod +x build/index.js
npm run watch            # tsc --watch
npm test                 # vitest in watch mode
npm run test:precommit   # vitest run (single pass) — what CI and the pre-commit hook use
npm run lint             # eslint src scripts
npm run lint:fix
npm run format           # prettier --write src/**/*.ts
npm run inspector        # MCP Inspector against build/index.js (build first)

Run a single test file or case:

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"

vitest.config.ts sets two things:

• exclude adds build/** to the defaults. Without it, tsc compiles the .test.ts files into build/, Vitest collects those copies alongside the sources, and every test runs twice locally — against stale compiled output, since tsc never removes artifacts for deleted source files. Collection is otherwise the Vitest default: src/**/*.test.ts plus the release scripts' scripts/*.test.mjs.
• silent: "passed-only" hides console output from passing tests. The handlers console.error in their catch blocks, so the error-path tests otherwise bury the results under stack traces. Consequence: a console.log added to debug a passing test prints nothing. Make the test fail, or run that file with --silent=false.

The husky pre-commit hook runs lint-staged (eslint --fix + prettier) followed by the full test suite, so commits are slow but pre-verified.

Architecture

An MCP stdio server wrapping the Open Library HTTP API. Three layers:

src/index.ts — the OpenLibraryServer class. Builds the two axios clients via createOpenLibraryClients, then drives both request handlers from TOOLS: ListTools maps the registry through toInputSchema, and CallTool looks the tool up by name. Reads its version at runtime from ../package.json relative to import.meta.url (resolves to the package root from build/index.js). The run() call is gated on process.argv[1] === new URL(import.meta.url).pathname so importing the module in tests doesn't start a transport. run() also owns the SIGINT handler: the constructor deliberately installs no process-wide listener, because the suite builds a server per test and those listeners accumulate (src/index.test.ts asserts construction adds none).