Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
| # Papers With Code MCP server specification | |
| This document records the agreed beta scope for the hosted Papers With Code MCP | |
| server. | |
| ## Product and hosting | |
| - Live in this repository as the separate `pwc-mcp` Python package and reuse the | |
| CLI's public HTTP transport rather than invoking the CLI as a subprocess. | |
| - Ship the canonical endpoint from the Papers With Code VPS at | |
| `https://paperswithcode.co/mcp`. The public Docker Space | |
| `huggingface/paperswithcode-mcp` remains an optional fallback without changing | |
| the MCP contract. | |
| - Serve anonymous, read-only requests. Search is deterministic and contains no | |
| embedded language model. | |
| - Use stateless Streamable HTTP at `/mcp`, advertising stock-client MCP | |
| `2025-11-25` while supporting experimental `2026-07-28` discovery. Expose | |
| `/health`, `/.well-known/mcp`, and generated `/docs` schema routes. | |
| ## Public contract | |
| Expose exactly one tool per read-only `pwc` CLI research command, with every | |
| research flag of that command as a tool parameter (`tests/test_parity.py` | |
| enforces this against the CLI parser): | |
| - `search_papers` (`pwc search`) | |
| - `get_paper_info` (`pwc paper info`) | |
| - `get_paper_evaluations` (`pwc paper evaluations`) | |
| - `read_paper` (`pwc paper read`) | |
| - `list_papers` (`pwc paper list`) | |
| - `list_recent_papers` (`pwc paper recent`) | |
| - `list_trending_papers` (`pwc paper trending`) | |
| - `get_related_papers` (`pwc paper related`) | |
| - `get_paper_lineage` (`pwc paper lineage list`) | |
| - `get_task` (`pwc task --name`) | |
| - `list_tasks` (`pwc task list`) | |
| - `get_method` (`pwc method --name`) | |
| - `list_methods` (`pwc method list`) | |
| - `get_conference` (`pwc conference --name`) | |
| - `list_conferences` (`pwc conference list`) | |
| - `get_organization` (`pwc organization --name`) | |
| - `list_organizations` (`pwc organization list`) | |
| - `get_framework` (`pwc framework --name`) | |
| - `list_frameworks` (`pwc framework list`) | |
| - `get_benchmark` (`pwc benchmark --name`) | |
| - `list_benchmarks` (`pwc benchmark list`) | |
| Tools run the CLI handlers in-process through the shared cached transport, so | |
| validation, fail-closed filter confirmation, and the JSON payload are the | |
| CLI's. Every result includes that payload as `data` beside typed projections. | |
| Terminal-only flags have no parameter. The hosted service caps `limit` at 25, | |
| returns compact official-first paper resources, and serves `read_paper` in | |
| chunks. `search_papers` defaults to hybrid mode, the same as `pwc search`. | |
| Expose these resource templates: | |
| - `pwc://papers/{paper}` | |
| - `pwc://papers/{paper}/markdown` | |
| - `pwc://tasks/{task}` | |
| - `pwc://benchmarks/{benchmark}` | |
| Expose `find_papers`, `compare_leaderboard`, and `survey_task` prompts. | |
| Responses use stable, MCP-specific versioned structured outputs with a text | |
| fallback. `read_paper` performs one upstream read of at most 64 KiB per call and | |
| returns a signed opaque continuation cursor when more Markdown remains. The | |
| cursor binds the original reference, canonical paper, content version, byte | |
| offset, chunk limit, key identifier, and fixed one-hour expiry. A continuation | |
| supplied with a different reference is honoured only when that reference | |
| resolves to the cursor's canonical paper. The current and previous signing keys | |
| support rotation without accepting unsigned state. | |
| Paper references accept arXiv IDs, numeric PwC external IDs, arXiv/Hugging | |
| Face/Papers With Code URLs, exact titles, and the unique short name before a | |
| title's colon. Ambiguous exact titles fail rather than selecting one result. | |
| A reference the catalog does not hold falls back to the public API's | |
| `papers/{reference}/public-metadata` endpoint (Hugging Face Papers, arXiv, or | |
| Crossref metadata with labelled `available_at` links), cached for an hour | |
| including misses, and marked `in_catalog: false`; full text is never fetched | |
| from outside the catalog. A title the endpoint rejects goes to | |
| `papers/public-metadata/search?title=`, which matches exact normalized titles on | |
| arXiv and Crossref (or the single arXiv paper sharing a "Name:" prefix, noted | |
| in the result). Misses say whether an identifier or a title was tried, or that | |
| the lookup was unavailable. A reference either endpoint maps to a catalog paper | |
| is retried with that paper's arXiv or catalog ID. | |
| Paper evaluations and benchmark leaderboards paginate. Leaderboards merge equivalent model rows across | |
| task scopes while retaining scoped ranks, protocol, split, shots, source, | |
| openness, and update time. Metric direction is explicit when known. | |
| ## Safety and operations | |
| - Require a strict configurable browser Origin allowlist; native clients may | |
| omit Origin. Never configure a wildcard Origin. | |
| - Enforce, per IP, 60 total requests/minute, 10 semantic or hybrid searches/minute, and | |
| four concurrent requests, plus a global ceiling of 128 concurrent requests. | |
| All four limits are overridable through `PWC_MCP_*_LIMIT` environment | |
| variables; the global ceiling also sizes the synchronous tool thread pool. | |
| List tools return at most 25 rows. | |
| - Set catalog timeouts to 25 seconds and bound HTTP request and upstream response | |
| bodies and serialized MCP responses to 2 MiB. | |
| - Log only tool name, status, latency, response bytes, protocol, and server | |
| version. Never log queries, paper identifiers, raw IPs, authorization values, | |
| or request/response bodies. | |
| - Cache tool/resource catalogs for one hour, taxonomy data for ten minutes, | |
| paper and benchmark data for five minutes, and search results for one minute. | |
| Cache immutable, versioned Markdown chunks for one hour within both a | |
| 256-entry and 16 MiB ceiling. | |
| - Bind to loopback on the VPS, trust forwarded identity only from an exact | |
| loopback peer, let a direct loopback client without `X-Forwarded-For` name | |
| its own rate-limit identity with `X-PwC-MCP-Client`, optionally trust the | |
| right-most untrusted `X-Forwarded-For` hop from peers in | |
| `PWC_MCP_TRUSTED_PROXY_CIDRS` (never their `X-PwC-MCP-Client`), and expose cached catalog readiness without making `/health` | |
| wait on an upstream call. | |
| ## Release | |
| Immutable releases must test the CLI contract and MCP server and build the | |
| Docker image. VPS deployment smoke-tests `/health`, the single `/mcp` endpoint, | |
| and the catalog continuation contract before nginx publication. Only tags | |
| matching `pwc-mcp-*` may additionally publish the fallback Space. | |