pubcrawl CLAUDE.md

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 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)

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). 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.

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.

NCBI Client (src/lib/ncbi.ts) — Wraps the four E-utilities endpoints (esearch, esummary, efetch, elink) plus pmidToPmcid. All requests go through rateLimitedFetch (300ms delay without API key, 100ms with) with a 15s timeout. Every request includes tool=pubcrawl and [email protected]. Each function checks the cache before making a network call.