DOI Citation Verifier MCP Server

<p align="center">
  <img src="icon.png" alt="doi-mcp logo" width="128" height="128">
</p>

<h1 align="center">DOI Citation Verifier MCP Server</h1>

<p align="center">
  A Model Context Protocol (MCP) server that <strong>prevents citation hallucination</strong> by verifying academic citations against <strong>9 authoritative databases</strong>. This server enables AI assistants to verify every citation against real publications before citing them.
</p>

## 🚀 Quick Install

```bash
npx -y github:tfscharff/doi-mcp
```

Or add to your Claude Desktop config:
```json
{
  "mcpServers": {
    "doi-mcp": {
      "command": "npx",
      "args": ["-y", "github:tfscharff/doi-mcp"]
    }
  }
}
```

## The Problem This Solves

Large language models sometimes "hallucinate" academic citations - citing papers that don't exist, misattributing real titles to wrong authors, or mixing up publication details. This MCP server eliminates that problem by:

1. **9-database verification**: Checks citations across CrossRef, OpenAlex, PubMed, zbMATH, ERIC, HAL, INSPIRE-HEP, Semantic Scholar, and DBLP
2. **Parallel search**: Queries all databases simultaneously for fast results (~1 second)
3. **Comprehensive coverage**: 600+ million publications across all disciplines including STEM, humanities, social sciences, and education
4. **DOI-backed citations**: Every verified citation includes a valid, clickable DOI

## Features

- **9 Database Search**: CrossRef, OpenAlex, PubMed, zbMATH, ERIC, HAL, INSPIRE-HEP, Semantic Scholar, DBLP
- **Verify Citations**: Check if a paper with specific details actually exists across all databases
- **Find Verified Papers**: Search for real papers on a topic and get only verified citations
- **Parallel Processing**: All database queries run simultaneously for maximum speed
- **LRU Caching**: Repeated queries return instantly (5-minute TTL)
- **Early Exit**: High-confidence matches (score ≥8) return immediately without waiting for all databases
- **Source Selection**: Search all databases or target specific sources
- **Citation Formatting**: Returns properly formatted citations with DOIs
- **Zero Configuration**: All databases work out-of-the-box with no API keys required
- **Fully Tested**: 41 tests covering scoring, caching, database adapters, and tool integration

## How It Works

When an AI assistant is asked about research or for citations:

1. **Without this MCP**: The assistant might cite "According to Smith et al. (2023) in Nature..." referencing a paper that doesn't exist
2. **With this MCP**: The assistant uses `verifyCitation` first, which searches across 9 databases in parallel and returns:
   - Verified match with full DOI → Can be cited
   - No match found → Cannot cite; must search for real papers instead

## Tools

### verifyCitation
**Primary anti-hallucination tool** - Verifies a citation exists across multiple databases before it can be mentioned.

**Input:**
- `title` (string, optional): Paper title (partial matches accepted)
- `authors` (array, optional): Author names (last names sufficient)
- `year` (number, optional): Publication year
- `doi` (string, optional): DOI if known
- `journal` (string, optional): Journal name

**Returns JSON with:**
- `verified`: true/false
- If verified=true: DOI, title, authors, year, journal, URL, source database
- If verified=false: Warning message that no matching publication was found
- Match quality indicators for transparency

**Example successful verification:**
```json
{
  "verified": true,
  "doi": "10.1038/s41586-023-06004-9",
  "title": "Accurate structure prediction of biomolecular interactions...",
  "authors": ["John Jumper", "Richard Evans", "..."],
  "year": 2023,
  "journal": "Nature",
  "url": "https://doi.org/10.1038/s41586-023-06004-9",
  "source": "crossref",
  "message": "✓ Citation verified"
}
```

### findVerifiedPapers
Search for real papers on a topic and return only verified citations with DOIs from multiple databases.

**Input:**
- `query` (string): Search query (topic, keywords, author names)
- `source` (string, optional): Which database to search - "all" (default), "crossref", "openalex", "pubmed", "zbmath", "eric", "hal", "inspirehep", "semanticscholar", or "dblp"
- `limit` (number, optional): Number of results per source (1-20, default: 5)
- `yearFrom` (number, optional): Minimum publication year
- `yearTo` (number, optional): Maximum publication year

**Returns:** Array of verified papers from the specified database(s) with complete citation information including source

**Example:**
```javascript
// Search all 9 databases
findVerifiedPapers({ query: "CRISPR gene editing", limit: 5 })

// Search only PubMed for biomedical papers
findVerifiedPapers({ query: "cancer immunotherapy", source: "pubmed", limit: 10 })

// Search zbMATH for mathematics papers
findVerifiedPapers({ query: "algebraic topology", source: "zbmath" })

// Search DBLP for computer science papers
findVerifiedPapers({ query: "neural networks", source: "dblp", yearFrom: 2020 })

// Search ERIC for education research
findVerifiedPapers({ query: "active learning pedagogy", source: "eric" })

// Search HAL for French/European humanities research
findVerifiedPapers({ query: "phenomenology Husserl", source: "hal" })

// Search INSPIRE-HEP for high-energy physics papers
findVerifiedPapers({ query: "Higgs boson", source: "inspirehep" })
```

## Installation

Add to your Claude Desktop config file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "doi-mcp": {
      "command": "npx",
      "args": ["-y", "github:tfscharff/doi-mcp"]
    }
  }
}
```

Restart Claude Desktop and the server will be available.

### Alternative: Global Install

```bash
npm install -g github:tfscharff/doi-mcp
```

Then use this config:
```json
{
  "mcpServers": {
    "doi-mcp": {
      "command": "doi-mcp"
    }
  }
}
```

### Alternative: Clone Locally

```bash
git clone https://github.com/tfscharff/doi-mcp.git
cd doi-mcp
npm install
npm run build
```

Config for local install:
```json
{
  "mcpServers": {
    "doi-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/doi-mcp/dist/index.js"]
    }
  }
}
```

## Troubleshooting

### Server not connecting
1. Check Node.js is installed: `node --version` (requires v18+)
2. Check Claude Desktop logs:
   - **Windows**: `%APPDATA%\Claude\logs\`
   - **macOS**: `~/Library/Logs/Claude/`
   - **Linux**: `~/.config/Claude/logs/`

### npx command fails
```bash
npm cache clean --force
```

### Testing locally
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development with watch mode
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Architecture

Version 4.0 uses a modular architecture for maintainability and testability:

```
src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── types.ts              # Shared interfaces
├── scoring.ts            # Match scoring algorithm
├── cache.ts              # LRU cache (5-min TTL)
├── http.ts               # Fetch utilities
├── tools/                # Tool handlers
│   ├── verifyCitation.ts
│   ├── batchVerifyCitations.ts
│   └── findVerifiedPapers.ts
└── databases/            # Database adapters
    ├── index.ts          # Parallel query orchestrator
    ├── crossref.ts
    ├── openalex.ts
    ├── pubmed.ts
    └── ... (9 adapters total)
```

**Adding a new database:**
1. Create `src/databases/newdb.ts` with `config`, `search()`, and `normalize()`
2. Import and add to `src/databases/index.ts`
3. Add tests in `tests/databases/newdb.test.ts`

## Example Usage

**Before this MCP (citation hallucination):**
```
User: "Tell me about recent AlphaFold research"
Assistant: "According to Johnson et al. (2024) in Science, AlphaFold3 achieved..."
           ❌ This paper doesn't exist
```

**After this MCP (verified citations only):**
```
User: "Tell me about recent AlphaFold research"
Assistant: [Uses findVerifiedPapers tool]
           "According to Jumper et al. (2023) in Nature (DOI: 10.1038/s41586-023-06004-9), 
            AlphaFold3 achieved..."
           ✓ Real paper with valid DOI verified across databases
```

**Verification catches fake citations:**
```
User: "Can you verify this citation: Smith et al. (2024), 'Quantum AI', Nature"
Assistant: [Uses verifyCitation tool - searches all 9 databases in parallel]
           "⚠ I cannot verify this citation - no matching publication found in
            any of the 9 databases. This citation may be incorrect."
```

## Database Coverage

All databases are queried in parallel for maximum speed (~1 second total):

### General Databases
- **CrossRef**: 150+ million scholarly publications across all disciplines
- **OpenAlex**: 250+ million scholarly works across all disciplines
- **Semantic Scholar**: 200+ million papers with AI-powered search

### Specialized Databases
- **PubMed**: 35+ million biomedical and life sciences publications
- **zbMATH**: 4+ million mathematics publications
- **DBLP**: Comprehensive computer science bibliography (journals and conferences)
- **ERIC**: 1.7+ million education research publications
- **HAL**: 4.4+ million French/European scholarly documents (2.5M English)
- **INSPIRE-HEP**: 1.7+ million high-energy physics publications

### Total Coverage
**600+ million publications** across all academic disciplines with specialized depth in STEM, computer science, biomedical sciences, mathematics, and education research.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Related

### API Documentation
- [CrossRef API](https://www.crossref.org/documentation/retrieve-metadata/rest-api/)
- [OpenAlex API](https://docs.openalex.org/)
- [PubMed API](https://www.ncbi.nlm.nih.gov/home/develop/api/)
- [zbMATH API](https://zbmath.org/api/)
- [ERIC API](https://eric.ed.gov/?api=)
- [HAL API](https://api.archives-ouvertes.fr/docs/)
- [INSPIRE-HEP API](https://github.com/inspirehep/rest-api-doc)
- [Semantic Scholar API](https://www.semanticscholar.org/product/api)
- [DBLP API](https://dblp.org/faq/How+to+use+the+dblp+search+API.html)

### Resources
- [DOI Handbook](https://www.doi.org/the-identifier/resources/handbook)
- [Model Context Protocol](https://modelcontextprotocol.io)