# Polymath MCP

An MCP (Model Context Protocol) server that aggregates free, keyless research
sources for computer science, computer engineering, electronics and IT.

One server, one normalized output format, seventeen data sources. Every source
works without an API key and without payment. Results from different sources
are merged and deduplicated by DOI and arXiv id, so the same paper found on
arXiv, Crossref and OpenAlex comes back as a single record that combines the
best fields of each.

## Why

Research data is scattered across many APIs, each with its own format, quirks
and rate limits. Existing MCP servers each cover one slice. Polymath gives an
agent a single interface where a paper, its open-access PDF, its citation
count, its implementation on GitHub, the model trained from it on Hugging Face
and the practical discussion around it on Hacker News or Stack Exchange are
all one tool call apart.

## Tools

| Tool | What it does | Sources |
|---|---|---|
| `search_papers` | Search academic papers, deduplicated across sources | arXiv, Crossref, DBLP, Europe PMC, OpenAlex, CORE, Zenodo, Semantic Scholar, Hugging Face Papers |
| `get_paper` | Resolve one paper by DOI or arXiv id, merging every source that knows it, including open-access PDF link and citation counts | the above, plus Unpaywall and OpenCitations |
| `search_code` | Find repositories, e.g. the implementation of a paper | GitHub |
| `search_hub` | Search models or datasets, with links back to their papers | Hugging Face Hub |
| `search_trends` | Practitioner discussions and relevance signals | Hacker News, Stack Overflow, Electronics Stack Exchange |
| `search_standards` | RFCs and Internet-Drafts | IETF Datatracker |
| `search_components` | Electronic component documents: scanned datasheets and KiCad symbols | Internet Archive, KiCad libraries |
| `list_sources` | List every source and its category | - |

Every search response is an envelope with `results`, `sources_ok` and
`sources_failed`. Partial failure is the normal case for an aggregator: when a
source is down or rate-limited, the others still answer and the envelope says
exactly which sources contributed.

## Installation

Requires Python 3.11+.

```bash
pip install git+https://github.com/Moreti2002/polymath-mcp
```

Or from a clone:

```bash
git clone https://github.com/Moreti2002/polymath-mcp
cd polymath-mcp
pip install .
```

### Claude Code

```bash
claude mcp add polymath -- polymath-mcp
```

### Claude Desktop / other MCP clients

```json
{
  "mcpServers": {
    "polymath": {
      "command": "polymath-mcp"
    }
  }
}
```

## Configuration

No API keys are needed. One optional environment variable:

- `POLYMATH_EMAIL`: a real contact e-mail. Unlocks the Unpaywall source
  (which requires it) and puts Crossref requests in its polite pool with
  better rate limits. Without it everything else still works.

```json
{
  "mcpServers": {
    "polymath": {
      "command": "polymath-mcp",
      "env": { "POLYMATH_EMAIL": "you@example.com" }
    }
  }
}
```

## Sources and their limits

All limits below are for keyless access, as observed in practice.

| Source | Role | Keyless limit |
|---|---|---|
| arXiv | CS/EE preprints, primary | 1 request / 3 s (self-imposed politeness) |
| Crossref | DOI metadata, primary | 3 req/s in the polite pool |
| DBLP | Canonical CS bibliography (venues) | ~1 req/s, aggressive blocking on bursts |
| Europe PMC | Full-text biomedical + applied ML | ~10 req/s |
| OpenAlex | Enrichment by DOI (free); text search is credit-rationed (~100 searches/day) | 1000 credits/day/IP |
| CORE | Institutional repository full-text | ~10 req/min |
| Zenodo | Software and datasets with DOIs | 30 req/min |
| Semantic Scholar | Citation graph, best effort only | shared anonymous pool, frequent 429 |
| Unpaywall | Open-access PDF resolution by DOI | 100k/day, requires `POLYMATH_EMAIL` |
| OpenCitations | Citation counts and references | unthrottled, high latency |
| GitHub | Repository search | 10 req/min |
| Hugging Face | Models, datasets, papers | generous, undocumented |
| Hacker News (Algolia) | Discussion search | ~10k req/h |
| Stack Exchange | Stack Overflow + Electronics SE | 300 req/day/IP |
| IETF Datatracker | RFCs and drafts | unthrottled |
| Internet Archive | Scanned datasheets and databooks | unthrottled |
| KiCad libraries (GitLab) | Component symbol existence | unthrottled |

The server caches responses in memory and throttles each source to stay
within these limits. Sources with hard daily budgets (Stack Exchange,
OpenAlex search) are cached the longest.

### Known coverage gaps

- There is no legitimate keyless API for commercial electronic component
  catalogs (Octopart/Nexar, Digi-Key and Mouser all require credentials).
  `search_components` covers what keyless sources can: scanned datasheets on
  the Internet Archive and KiCad symbol libraries. For part selection
  discussion, `search_trends` includes the Electronics Stack Exchange.
- Papers with Code shut down in 2025; its role is covered by the Hugging Face
  Papers source.
- Semantic Scholar without a key shares a global anonymous pool and fails
  often. It is wired as best-effort and never blocks a search.

## Architecture

```
src/polymath/
  server.py        MCP server and tool definitions
  models.py        normalized result models (Paper, CodeRepo, HubItem, ...)
  aggregate.py     concurrent fan-out with per-source failure isolation
  dedupe.py        cross-source paper merging (DOI, arXiv id, title)
  http.py          shared HTTP client, retries, per-source throttling
  cache.py         in-memory TTL cache
  providers/       one module per source, registered in a plug-in registry
```

Adding a source is one file: subclass `Provider` (or `PaperLookupProvider`),
map the API response to the normalized models, decorate the class with
`@register`. The aggregator, dedupe and MCP tools pick it up automatically.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest -m "not live"   # offline tests (mocked HTTP)
pytest -m live         # integration tests against the real APIs
```

Offline tests must always pass. Live tests depend on third-party services and
may fail when a source is down or rate-limited; CI runs them as non-blocking.

## License

MIT. See [LICENSE](LICENSE).