# BioLit MCP

**Citation-grounded biomedical literature review for Claude.** An MCP server over PubMed, Europe PMC, NCBI Gene and UniProt, an *Evidence Review* agent skill, and a 50-question benchmark that measures whether answers can be trusted.

Scientists don't adopt AI research assistants that invent citations. BioLit is built around one rule: **Claude may only cite papers it has actually retrieved and read in the session**, and the benchmark checks that every cited PMID exists and supports its claim.

```mermaid
flowchart LR
    U[Scientist] --> C[Claude + Evidence Review skill]
    C -- MCP --> S[BioLit server]
    S --> P[PubMed E-utilities<br/>search]
    S --> E[Europe PMC<br/>abstracts + citation check]
    S --> G[NCBI Gene]
    S --> UP[UniProt Swiss-Prot]
    C --> A[Answer: claims → PMIDs]
    A --> B[Benchmark: PMID exists? claim supported?]
```

## Tools

| Tool | Source | Returns |
|---|---|---|
| `search_pubmed(query, max_results, min_year)` | NCBI E-utilities | PMIDs, titles, journals, years, publication types |
| `get_abstracts(pmids)` | Europe PMC | Abstracts + metadata; non-existent PMIDs listed in `not_found` |
| `lookup_gene(symbol, taxon_id)` | NCBI Gene | Official name, chromosome, cytogenetic location, aliases, summary |
| `lookup_protein(gene_symbol, taxon_id)` | UniProt | Reviewed accession, protein name, length, function |

All tools are read-only. Production details: request timeouts, retry with exponential backoff on 429/5xx, NCBI rate limiting (3 req/s, or 10 req/s with `NCBI_API_KEY`), input validation, and error messages that are safe to show the model.

## Quick start

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

**Claude Code**
```bash
claude mcp add biolit -- uvx --from git+https://github.com/sanikacentric/biolit-mcp biolit-mcp
mkdir -p ~/.claude/skills && cp -r skills/evidence-review ~/.claude/skills/
```

**Claude Desktop** (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "biolit": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sanikacentric/biolit-mcp", "biolit-mcp"],
      "env": { "NCBI_EMAIL": "you@example.com" }
    }
  }
}
```

**Remote (Streamable HTTP):** `biolit-mcp --transport streamable-http`

Optional environment variables: `NCBI_API_KEY` (higher rate limit), `NCBI_EMAIL` (recommended by NCBI).

Then ask: *"What is the evidence that lecanemab slows cognitive decline in early Alzheimer's disease?"*

## Evidence Review skill

[`skills/evidence-review/SKILL.md`](skills/evidence-review/SKILL.md) gives Claude a scientist's workflow: resolve entities → run focused searches → read abstracts → write one claim per sentence with PMIDs → self-check every citation before answering. The output separates the bottom line, evidence, strength & gaps, and references.

## Benchmark

[`evals/`](evals) runs 50 questions with and without the BioLit tools:

- **30 fact questions:** UniProt accession + chromosome for well-characterized human genes, scored exactly.
- **20 literature questions:** across oncology, cardiometabolic, neuro, gene therapy and structural biology. Every cited PMID is checked live against PubMed, and an LLM judge decides whether the cited abstracts support each claim.

| Metric | What it measures |
|---|---|
| `fact_accuracy_%` | Accession and chromosome both correct |
| `citation_validity_%` | Cited PMIDs that exist |
| `hallucinated_pmids` | Cited PMIDs that don't exist |
| `claim_support_%` | Claims supported by their cited abstracts |

```bash
pip install -e ".[eval]"
export ANTHROPIC_API_KEY=...
python evals/run_eval.py --mode both              # full run (~100 agent runs)
python evals/run_eval.py --mode tools --limit 3   # smoke test
```

### Results

_Results go here after the first full run (`evals/results/*.json`)._

## Development

```bash
pip install -e ".[dev,eval]"
pytest          # unit tests with recorded API responses; no network or API key needed
ruff check . && ruff format --check .
```

## Limitations

- Evidence is read from abstracts, not full text.
- The claim-support judge is an LLM. Spot-check its verdicts before relying on the numbers.
- Not for clinical decision-making.

## License

MIT