# literature-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an agent direct search
access to the main academic literature APIs plus PDF full-text extraction. It is a
thin wrapper: each tool calls one upstream API and returns that API's own fields,
rather than merging everything into a normalised record. That matters when you want
per-source details — arXiv's `pdf_url`, Semantic Scholar's `openAccessPdf`, Crossref's
`container-title` — that an aggregator would drop.

## Tools

| Tool | Upstream | What it returns |
|------|----------|-----------------|
| `search_arxiv` | `export.arxiv.org/api/query` | title, arXiv id, abs/pdf URLs, published date, year, authors, DOI, abstract |
| `search_crossref` | `api.crossref.org/works` | title, DOI, authors, journal, year, abstract |
| `search_semanticscholar` | `api.semanticscholar.org/graph/v1` | title, year, venue, authors, external ids, abstract, open-access PDF URL |
| `search_tavily` | `api.tavily.com/search` | title, URL, relevance score, snippet — web results, lower confidence than the paper databases |
| `extract_url` | `api.tavily.com/extract` | clean readable text of one web page |
| `read_paper_pdf` | local file or URL (PyMuPDF) | page count and full extracted text; downloads the PDF first if given a URL |

The first three need no credentials. `search_tavily` and `extract_url` require a
Tavily API key. No key is hard-coded in the source — everything is read from the
environment or a `.env` file next to the package.

Every search tool takes optional `year_from` / `year_to` filters and caps result
counts at 50 to stay inside the upstream rate limits. HTTP 429 responses are retried
once with a short backoff.

## Install

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

```bash
git clone https://github.com/SinCircle/literature-mcp.git
cd literature-mcp
cp .env.example .env      # then edit .env and add your keys
uv sync
```

The server communicates over stdio and writes only logs to stderr, so it will not
corrupt the JSON-RPC stream. Point any MCP client at:

```bash
uv run --project /absolute/path/to/literature-mcp literature-mcp
```

## Configuration

All settings are optional and read from the environment (via `.env` or exported
variables):

| Variable | Purpose |
|----------|---------|
| `TAVILY_API_KEY` | Required for `search_tavily` and `extract_url`. |
| `LITERATURE_MCP_CONTACT_EMAIL` | Sent to Crossref's polite pool and used in the `User-Agent`. A real address gets faster, more reliable service. |
| `SEMANTIC_SCHOLAR_API_KEY` | Optional; raises Semantic Scholar rate limits above the shared public tier. |
| `LITERATURE_MCP_PDF_DIR` | Where `read_paper_pdf` saves PDFs downloaded from URLs. Defaults to `~/literature-mcp/pdfs`. |

## Verify

```bash
uv run python -c "
import asyncio, literature_mcp.server as s
print([t.name for t in asyncio.run(s.mcp.list_tools())])
"
```

Expect the six tool names listed above. To smoke-test a live call without an agent:

```bash
uv run python -c "
import asyncio
from literature_mcp.server import search_crossref
print(asyncio.run(search_crossref('Kalman filter', rows=2)))
"
```

`search_crossref` is the friendliest target for a smoke test: it needs no API key and
its rate limit is far more forgiving than arXiv's, which throttles aggressively and
returns HTTP 429 if you call it more than a few times a minute.

## Notes and limitations

- The search tools return metadata only. Use `read_paper_pdf` for the text, or the
  `open_access_pdf` / `pdf_url` fields to find a copy.
- `read_paper_pdf` returns an empty `text` plus a note when a PDF is scanned images
  with no text layer; run those through OCR yourself.
- Results are returned in upstream order. No ranking, deduplication, or
  cross-source merging is applied — that is deliberate, and left to the caller.
- Tool outputs are truncated (`read_paper_pdf` at `max_chars`, Tavily snippets at a
  few thousand characters) to keep responses inside an agent's context budget.

## License

MIT — see [LICENSE](LICENSE).