mcp_server/SPEC.md

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.