📜 What is Paper-Research-MCP?

A brand-new MCP server for academic paper search, distilled from the expansion plan in Collection/Markdown/Refer/Reference.md — absorbed while curating three upstream collections plus that additional reference, to make agent-side research broader, not just deeper.

It implements the document's core design rule: don't flatten every source into one search_papers(). Each source is its own connector with its own tools (discovery, conference review, paper↔code mapping, metadata resolution, OA resolution), and a federation layer on top handles cross-source search, deduplication, and provenance.

• 🔓 Free-first — everything runs without an API key; premium connectors are registered but dormant until you set their env vars
• 🧵 Federated — cross-source search with DOI → title dedup and alsoIn/matchedQueries provenance
• 📅 Date-bounded — year_from/year_to passed natively to APIs that support it, universal post-filter for the rest
• 📦 uv-packaged — Python ≥ 3.10, deps only mcp + httpx
• 🟢 Honest failures — bot-walls and rate limits return structured envelopes with manual-fallback suggestions, never silent lies

📦 Install

Requires: Python ≥ 3.10 and uv. Deps: mcp + httpx.

Local checkout — point your MCP client at the folder:

// ZCode / Claude Desktop / Cursor / any MCP client
{
  "mcpServers": {
    "paper-research": {
      "command": "uv",
      "args": ["--directory", "<path>/Paper-Research-MCP", "run", "paper-research-mcp"],
      "env": { "S2_API_KEY": "", "ADS_TOKEN": "", "SCOPUS_API_KEY": "" }
    }
  }
}

Published on PyPI — after release (see 🚀 Publishing below) it becomes one line:

{ "mcpServers": { "paper-research": { "command": "uvx", "args": ["paper-research-mcp"] } } }

🔑 Optional API keys

All free connectors work without any key. Premium connectors stay dormant until their env var is set (see .env.example):

🌐 Connectors

🇮🇩 The indonesia_research block follows the Reference.md warning: these platforms have no official APIs — they are best-effort scrapers with truthful failure envelopes.

🛠 Tools

34 tools are auto-discovered by any MCP client via tools/list — no configuration needed. Two entry points worth knowing:

• search_papers — federated search; supports single query or parallel queries: ["k1","k2"], date bounds year_from/year_to, source selection, dedup by DOI → title, and provenance (alsoIn + matchedQueries)
• list_sources — every connector with its access category and env status

Full per-source tools (e.g. openalex_search, openreview_notes, garuda_search) are listed by your client automatically after connecting.

🏗 Architecture

pyproject.toml                      ← uv package ([project.scripts] paper-research-mcp)
└── src/paper_research_mcp/
    ├── server.py                   ← MCP stdio entry (official `mcp` SDK, lowlevel Server)
    ├── registry.py                 ← 30 connectors, auth-gating, universal year post-filter
    ├── federation.py               ← search_papers: queries×sources parallel (pool 8), dedup, provenance
    ├── core.py                     ← httpx w/ timeout, standardized item schema, envelopes, year filter
    └── sources/
        ├── free.py        (11)  OpenAlex Crossref arXiv DOAJ S2 OpenReview INSPIRE ERIC Unpaywall ORCID PwC
        ├── indonesia.py    (8)  GARUDA SINTA OneSearch RAMA Moraref Neliti BRIN Google Scholar
        ├── china.py        (5)  NSSD Baidu Scholar AMiner ScienceDB CSTR
        └── premium.py      (6)  ADS AlphaXiv Scopus Lens Dimensions WoS

🧪 Testing

uv run python tests/e2e_all_tools.py

Live suite with 36 checks: all 34 tools one by one (envelope-shape validation + per-category status expectations), all three federation modes, year-filter leak checks, and the MCP stdio handshake in a subprocess. Scraper sources returning blocked count as PASS — the envelope is the contract, not the network mood. Last run: 36/36 PASS.

🚀 Publishing

# 1. Create a PyPI account → Account Settings → API token
# 2. Dry-run against TestPyPI (optional):
uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-XXXXXXXX
# 3. Release:
uv build
uv publish --token pypi-XXXXXXXX
# 4. Anyone can now run it:
uvx paper-research-mcp

📄 License

MIT. Source of the connector plan: Collection/Markdown/Refer/Reference.md (paper-search-mcp ecosystem + indonesia_research + China platforms + premium connectors).