DOI Citation Verifier

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Model Context Protocol (MCP) server that prevents citation hallucination by verifying academic citations against multiple authoritative databases (CrossRef, OpenAlex, and PubMed). It's built using the `@modelcontextprotocol/sdk` and deployed via Smithery. ## Key Architecture ### Single File Design The entire MCP server is implemented in `src/index.ts` (~640 lines). This single-file architecture is intentional for simplicity and maintainability of an MCP server. ### Core Components 1. **Multi-Source Search** (`searchMultipleSources` function) - Queries three databases in parallel: CrossRef, OpenAlex, and PubMed - Returns aggregated results with error handling per source - Each API has different request formats and response structures 2. **Result Normalization** (`normalizeResult` function) - Converts heterogeneous API responses into a unified `NormalizedPaper` interface - Handles PubMed's two-step process (search for PMIDs, then fetch metadata) - Extracts DOIs from PubMed XML responses via `getDOIFromPubMed` 3. **Match Scoring** (`calculateMatchScore` function) - Scores potential matches based on title, year, authors, and journal - Score threshold (3+) determines if a citation can be verified - Higher scores (5+) indicate "high confidence" matches 4. **Two Primary Tools** - `verifyCitation`: Verifies if a specific citation exists (anti-hallucination tool) - `findVerifiedPapers`: Searches for real papers on a topic across databases 5. **MCP Resources & Prompts** - `citation://databases`: JSON resource listing database coverage - `citation://guidelines`: Markdown resource with usage best practices - `citation-verification-rules`: Prompt template enforcing verification-first workflow ### Tool Annotations Both tools include MCP annotations: - `readOnlyHint: true` - Tools don't modify data - `destructiveHint: false` - Safe to call repeatedly - `idempotentHint: true` - Same inputs produce same outputs ## Development Commands ```bash # Install dependencies npm install # Build TypeScript to dist/ npm run build # Watch mode for development npm run dev # Test with Smithery CLI (after installing @smithery/cli) npx @smithery/cli dev ``` ## API Integration Details ### CrossRef API - Base: `https://api.crossref.org/works` - No authentication required - Supports query filters for publication date ranges - Response: `message.items[]` array of works ### OpenAlex API - Base: `https://api.openalex.org/works` - Requires User-Agent header (polite pool access) - Year filters use different syntax: `publication_year:YYYY` or ranges - Response: `results[]` array of works ### PubMed API (NCBI E-utilities) - Two-step process: 1. `esearch.fcgi` - Search for PMIDs matching query 2. `esummary.fcgi` - Fetch metadata for PMIDs - DOIs require additional XML fetch via `efetch.fcgi` with XML parsing - Date ranges specified as `YYYY:YYYY[dp]` in query string ## Key Implementation Patterns ### Error Handling - External API failures are caught and added to `results.errors[]` - The system continues querying other sources if one fails - Partial results are still returned and normalized ### DOI Resolution Priority If a DOI is provided to `verifyCitation`, it's checked first via DOI.org API before falling back to text-based search. This provides the most reliable verification path. ### Deduplication `findVerifiedPapers` deduplicates results across sources using DOI or lowercase title as a unique key to avoid duplicate citations from multiple databases. ## Smithery Deployment The server is deployed to Smithery automatically on git push. Quality score factors: - Tool annotations (implemented: readOnlyHint, destructiveHint, idempotentHint) - Optional configuration (no required config improves score) - Icon files (icon.png, icon.svg in repository root) - Runtime specified as "typescript" in smithery.yaml ## TypeScript Configuration - Target: ES2022 with Node16 module resolution - Output: `dist/` directory (gitignored) - Declarations: Generated (.d.ts files) - Entry point: `dist/index.js` (specified in package.json) ## Export Pattern The default export is a factory function: ```typescript export default function createServer() ``` This allows the MCP runtime to instantiate the server and returns the initialized `server.server` instance. The server requires no configuration to function.