pubcrawl: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

PubCrawl is an MCP (Model Context Protocol) server that gives LLM clients (Claude Desktop, Cursor, etc.) access to PubMed, FDA/UK drug labelling, and ClinicalTrials.gov. Built by PharmaTools.AI.

Commands

• npm run build — compile TypeScript (src/) to dist/
• npm start — run the compiled MCP server via stdio
• npm run start:http — run it over Streamable HTTP (PORT, default 3000)
• docker build -t pubcrawl . && docker run -p 8080:8080 pubcrawl — container image
• npm run dev — tsc --watch for development
• npm test — run the Vitest unit suite (tests/)
• npm run test:watch — Vitest in watch mode
• npm run coverage — Vitest with v8 coverage
• npm run lint — ESLint (flat config, typescript-eslint)
• npm run toolspec — regenerate deploy/agent-registry/toolspec.json after npm run build (-- --check to verify)

Testing

Vitest unit tests live in tests/ and cover the pure logic layers: the XML/JATS/SPL parsers (xml-parser.ts), the LRU cache (cache.ts), the shared esummary→article formatter (pubmed-format.ts), the Europe PMC result mapper (europepmc.ts), the citation formatters (cite.ts), and the ClinicalTrials.gov summary mapper (clinicaltrials.ts), plus http.test.ts, which starts the real HTTP app on a local port and checks the transport and handshake (it calls no tools). Tests use fixture payloads — no network calls. Functions that need testing are exported from their module; keep new parsing/formatting logic as exported pure functions so it can be unit-tested the same way. CI (.github/workflows/build.yml) runs lint → test → build on every push and PR, plus a container job that builds and smoke-tests the Docker image.

Architecture

The server has three layers:

Tools (src/tools/) — Each file exports a register*Tool(server: McpServer) function that registers one MCP tool with a zod schema and async handler. Handlers return { content: [{ type: "text", text: JSON.stringify(...) }] } on success, adding isError: true on failure.