# 📄 paper-mcp

An MCP server built with **FastMCP** for paper, citation, author, and bibliography search.
Run it in one command with **uvx** — no manual install needed.

---

## ✨ Features

### Paper tools

| Tool | Returns |
|------|---------|
| `paper_get_metadata` | Title, authors, abstract, DOI, arXiv ID, citation count, TL;DR, OA status, fields of study |
| `paper_get_pdf` | Best open-access PDF URL |
| `paper_get_fulltext` | Full text plus structured pages, sections, and extracted tables |
| `paper_get_citations` | Up to 100 papers that cite this one |
| `paper_get_references` | Up to 100 papers this one cites |
| `paper_search` | Filtered, deduplicated search across S2, OpenAlex, PubMed, and DBLP |
| `paper_get_publication_status` | Venue, publisher, version of record, and preprint status |
| `paper_get_bibtex` | BibTeX citation from Semantic Scholar or Crossref |
| `paper_get_similar` | Related-paper recommendations |
| `paper_batch_lookup` | Up to 500 paper IDs in one Semantic Scholar request |
| `doi_get_metadata` | DOI metadata merged from Crossref, Semantic Scholar, and Unpaywall |

### Author and source tools

| Tool | Returns |
|------|---------|
| `author_search` | Disambiguated Semantic Scholar author matches |
| `author_get_profile` | h-index, affiliations, paper and citation counts |
| `author_get_papers` | A researcher's bibliography |
| `openalex_search` | Broad OpenAlex work search with institutions and topics |
| `pubmed_search` | PubMed biomedical article summaries |
| `dblp_search` | Curated DBLP computer-science bibliography results |

`paper_search` accepts `sources`, year range, venue, author, publication type,
minimum citations, open-access-only, and relevance/year/citation sorting.
Full text uses **arXiv HTML → structured open-access PDF extraction → Lightpanda → abstract**.
Responses from repeated Semantic Scholar searches and batch lookups are cached in memory.

---

## 🚀 Quick Start

### Run without installing (uvx)

```bash
# stdio mode — for Claude Desktop / most MCP clients
uvx paper-mcp

# SSE mode — for remote or multi-client setups
uvx paper-mcp --transport sse --port 8000
```

> `uvx` downloads, installs (in an isolated env), and runs the package — zero setup.

### Install permanently

```bash
uv tool install paper-mcp
paper-mcp                        # now available globally
paper-mcp --transport sse
```

### Local development

```bash
git clone https://github.com/imnotdev25/paper-search
cd paper-search
uv sync                                 # install all deps from pyproject.toml
uv run paper-mcp                 # run directly
uv run paper-mcp --transport sse
```

---

## 🖥 Claude Desktop Config

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "papers": {
      "command": "uvx",
      "args": ["paper-mcp"]
    }
  }
}
```

No Python paths, no venv activation — `uvx` handles everything.

---

## 🌐 Browser Fallback (gomcp / Lightpanda)

For JS-rendered publisher pages, the server automatically starts a
[Lightpanda](https://lightpanda.io) headless browser via
[gomcp](https://github.com/lightpanda-io/gomcp).

**One-time setup:**
```bash
# Download gomcp binary from GitHub releases:
# https://github.com/lightpanda-io/gomcp/releases

# Then download the Lightpanda browser binary:
gomcp download
```

If `gomcp` is not installed, the server still works — browser-dependent
paths fall back to abstract/metadata gracefully.

---

## 🏗 Architecture

```
Claude (LLM)
    │  MCP (stdio or SSE)
    ▼
paper-mcp  [FastMCP, Python]
    │
    ├── Semantic Scholar API  ──  metadata, citations, references
    ├── arXiv API + HTML      ──  preprint info + full text
    ├── Crossref + Unpaywall  ──  DOI metadata, BibTeX, OA PDFs
    ├── OpenAlex / PubMed / DBLP ── corpus-specific search
    └── gomcp SSE  ───────────── Lightpanda browser (JS fallback)
             │  CDP
             └── Lightpanda Browser (headless)
```

---

## 📦 Publishing to PyPI

```bash
# Build
uv build

# Publish (needs PyPI token)
uv publish --token $PYPI_TOKEN
```

Once on PyPI, anyone can run it with `uvx paper-mcp`.

---

## ⚙️ CLI Options

```
usage: paper-mcp [-h] [--transport {stdio,sse}] [--port PORT] [--host HOST]

options:
  --transport  stdio (default) or sse
  --port       SSE port (default: 8000)
  --host       SSE host (default: 127.0.0.1)
```

---

## 🔑 Notes

- Set `S2_API_KEY` for authenticated Semantic Scholar requests.
- Set `UNPAYWALL_EMAIL` to a real contact address to enable Unpaywall. Requests are
  skipped when it is unset; no placeholder identity is sent.
- Optionally set `OPENALEX_EMAIL` for the OpenAlex polite pool.
- `PAPER_CACHE_TTL` controls the in-memory cache in seconds (default `3600`; `0` disables it).
- PDF extraction is limited to open PDFs up to 25 MB and 50,000 extracted characters.
  Paywalled PDFs still require institutional access.

---

## 📁 Project Structure

```
paper-mcp/
├── pyproject.toml                  ← packaging, entry point, deps
├── README.md
├── src/
    └── paper_mcp/
        ├── __init__.py
        └── server.py               ← FastMCP tools + main()
└── tests/
    └── test_server.py              ← focused HTTP, PDF, cache, and config tests
```