mcp-pubmed-server-pancrpal: 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

A PubMed MCP Server providing structured biomedical literature retrieval for LLM agents. TypeScript codebase with agentic-friendly response models. Focuses on data provision, not analysis.

Commands

npm install          # Install dependencies
npm run build        # TypeScript -> dist/
npm run dev          # Dev mode with tsx --watch
npm run dev:http     # Dev mode with HTTP transport
npm start            # Production (stdio)
npm run start:http   # Production (HTTP)
npm run typecheck    # Type check without emitting

Architecture

src/
├── index.ts                  # Entry point
├── config.ts                 # All config constants + env parsing
├── server.ts                 # PubMedDataServer orchestrator
├── types/
│   ├── article.ts            # Article, SearchResult, OAInfo types
│   ├── responses.ts          # AgentResponse<T>, makeResponse/makeError helpers
│   └── index.ts              # Re-exports
├── api/
│   ├── pubmed-client.ts      # PubMed EUtilities client (search/fetch/rate-limit)
│   └── key-pool.ts           # Multi-key pool (round-robin/failover/random)
├── cache/
│   ├── memory-cache.ts       # In-memory LRU cache (5min TTL, 100 max)
│   └── file-cache.ts         # File-based persistent cache (30-day expiry)
├── services/
│   ├── fulltext.ts           # OA detection (PMC/Unpaywall/Publisher) + PDF download
│   └── system.ts             # Platform detection + download tool availability
├── tools/
│   ├── definitions.ts        # MCP tool schemas (8 tools)
│   └── handlers.ts           # Tool routing + implementation
├── transport/
│   ├── stdio.ts              # stdio transport
│   └── streamable-http.ts    # Express-based HTTP transport
└── utils/
    └── formatter.ts          # Article formatting (compact/standard/detailed)

MCP Tools (8 total)