Prototype PwC MCP Space from pwc-cli@6a547659

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12.11-slim-bookworm
+
+COPY --from=ghcr.io/astral-sh/uv:0.8.15 /uv /uvx /bin/
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PWC_MCP_HOST=0.0.0.0 \
+    PORT=7860
+
+RUN useradd --create-home --uid 1000 app
+WORKDIR /app
+
+COPY standalone_cli /src/standalone_cli
+COPY mcp_server /src/mcp_server
+RUN uv sync --project /src/mcp_server --frozen --no-dev --no-editable
+
+USER app
+ENV PATH="/src/mcp_server/.venv/bin:$PATH"
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/health', timeout=4)"
+
+CMD ["pwc-mcp"]

README.md

@@ -1,10 +1,24 @@
 ---
-title: Paperswithcode Mcp
-emoji: 🚀
-colorFrom: pink
+title: Papers With Code MCP
+emoji: 📚
+colorFrom: yellow
 colorTo: blue
 sdk: docker
-pinned: false
+app_port: 7860
+suggested_hardware: cpu-upgrade
+short_description: Read-only MCP access to the Papers With Code catalog
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Papers With Code MCP
+
+Anonymous, read-only access to papers, tasks, methods, benchmarks, and
+leaderboards through Model Context Protocol.
+
+- MCP endpoint: `/mcp`
+- Health endpoint: `/health`
+- Source: <https://github.com/huggingface/pwc-cli>
+- Built from `huggingface/pwc-cli@6a547659644bce05a246a0e20029699dbe2850e1`
+  (`pwc-mcp` 0.2.10, the release live at `https://paperswithcode.co/mcp`)
+
+Prototype: catalog reads go to the public `https://paperswithcode.co/api/v1`
+and share its anonymous rate limits.

mcp_server/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12.11-slim-bookworm
+
+COPY --from=ghcr.io/astral-sh/uv:0.8.15 /uv /uvx /bin/
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PWC_MCP_HOST=0.0.0.0 \
+    PORT=7860
+
+RUN useradd --create-home --uid 1000 app
+WORKDIR /app
+
+COPY standalone_cli /src/standalone_cli
+COPY mcp_server /src/mcp_server
+RUN uv sync --project /src/mcp_server --frozen --no-dev --no-editable
+
+USER app
+ENV PATH="/src/mcp_server/.venv/bin:$PATH"
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860/health', timeout=4)"
+
+CMD ["pwc-mcp"]

mcp_server/README.md

@@ -0,0 +1,139 @@
+# pwc MCP server
+
+Anonymous, read-only Model Context Protocol access to the public
+[Papers With Code](https://paperswithcode.co) catalog.
+
+The server uses stock-client MCP `2025-11-25` over Streamable HTTP and also
+serves experimental `2026-07-28` discovery on the same `/mcp` endpoint. It
+returns versioned structured output with compact Markdown fallbacks.
+
+## Run locally
+
+```bash
+uv run --project mcp_server pwc-mcp
+```
+
+The default listener is `127.0.0.1:7860`. Set `PWC_MCP_HOST`, `PORT`, or
+`PWC_API_URL` to override the bind address, HTTP port, or compatible PwC API.
+
+```bash
+curl http://127.0.0.1:7860/health
+```
+
+## Tools
+
+Every read-only `pwc` CLI research command is one tool, and every research flag
+of that command is a tool parameter, so results match `pwc ... --json`. Each
+result carries `schema_version` and `data`, the complete CLI JSON payload, next
+to typed projections such as `items` or `evaluations`.
+
+| Tool | CLI command |
+| --- | --- |
+| `search_papers` | `pwc search` |
+| `get_paper_info` | `pwc paper info` |
+| `get_paper_evaluations` | `pwc paper evaluations` |
+| `read_paper` | `pwc paper read` (64 KiB chunks with a continuation cursor) |
+| `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` |
+
+Parameter names follow the CLI flags except for the established MCP names
+`published_after`/`published_before` (`--start-date`/`--end-date`), `limit`
+(`--page-size`), `authors` (`--author`), `order_direction` (`--order-dir`),
+`minimum_evaluations` (`--min-eval-count`), and `include_evaluations`
+(`--include-evals`). Terminal-only flags (`--json`,
+`--implementation-coverage`, `--flat`) have no parameter because MCP output is
+always structured. Hosted differences from the CLI: `limit` is capped at 25,
+`get_paper_info` returns compact official-first resources, and `read_paper`
+is chunked. `search_papers` defaults to `hybrid` mode like `pwc search`.
+`tests/test_parity.py` fails when the CLI parser and the tool schemas drift.
+
+All tools are annotated read-only and idempotent. Search is deterministic;
+the caller controls hybrid (default), keyword, or semantic mode. `read_paper`
+fetches at most one 64 KiB catalog chunk per call and returns a signed, one-hour
+continuation cursor when more Markdown remains. Continuations stay pinned to
+the resolved paper and content version, so a changed paper fails with an
+explicit restart response; any reference that resolves to the same paper (the
+numeric catalog ID after starting from the arXiv ID, say) may carry the cursor.
+A placeholder cursor such as `"next"` with nothing saved reads from the
+beginning.
+
+Paper tools fall back to the public API's `public-metadata` endpoint for papers
+the catalog does not hold: `get_paper_info` and `read_paper` return Hugging Face
+Papers, arXiv, or Crossref (DOI) metadata and the abstract with
+`in_catalog: false`, a `note`, and labelled `available_at` links to cite instead
+of a Papers With Code page; `get_related_papers` returns a catalog search for the
+public title with the same `note` and links. A reference the endpoint maps to a
+catalog paper returns the catalog paper. Titles go to the sibling
+`public-metadata/search` endpoint, which accepts only an exact arXiv or Crossref
+title match, or the single arXiv paper sharing the "Name:" before its colon.
+`get_benchmark` answers a metric the leaderboard does not report with the
+unfiltered leaderboard and a `metric_note` naming the available metrics.
+
+## Resources
+
+- `pwc://papers/{paper}`
+- `pwc://papers/{paper}/markdown`
+- `pwc://tasks/{task}`
+- `pwc://benchmarks/{benchmark}`
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `PWC_API_URL` | Compatible catalog API; defaults to production PwC |
+| `PWC_MCP_HOST` | Listener address; defaults to loopback (`127.0.0.1`) |
+| `PWC_MCP_ALLOWED_HOSTS` | Comma-separated HTTP Host allowlist |
+| `PWC_MCP_ALLOWED_ORIGINS` | Comma-separated browser Origin allowlist |
+| `PWC_MCP_CURSOR_KEY_CURRENT` | Required secret used to sign continuation cursors |
+| `PWC_MCP_CURSOR_KEY_PREVIOUS` | Optional previous secret accepted during key rotation |
+| `PORT` | HTTP port; defaults to `7860` |
+| `PWC_MCP_REQUEST_LIMIT` | Requests per client per minute; defaults to `60` |
+| `PWC_MCP_SEMANTIC_LIMIT` | Semantic or hybrid searches per client per minute; defaults to `10` |
+| `PWC_MCP_CONCURRENCY_LIMIT` | Concurrent requests per client; defaults to `4` |
+| `PWC_MCP_GLOBAL_CONCURRENCY_LIMIT` | Concurrent requests across all clients; defaults to `128` and sizes the tool thread pool |
+| `LOG_LEVEL` | Content-free operational log level |
+
+Native clients may omit `Origin`. Browser requests must match the configured
+allowlist. A first-party client on the same host may send
+`X-PwC-MCP-Client: <token>` to name its rate-limit identity (for example one
+hashed chat session); the header counts only on a direct loopback connection
+without `X-Forwarded-For`, so proxied public traffic cannot use it. The server does not log queries, paper references, request bodies,
+raw IP addresses, or authorization headers.
+
+The hosted defaults allow 60 total requests and 10 semantic or hybrid searches per minute
+per client IP, with at most four concurrent requests per IP and 128 globally.
+Tool inputs cap list results at 25, catalog calls time out after 25 seconds, and
+request, upstream, and serialized MCP response bodies are bounded to 2 MiB.
+The global ceiling is 128 concurrent requests by default.
+Markdown chunks use a bounded 256-entry/16 MiB in-memory cache.
+
+`GET /.well-known/mcp` exposes connection metadata and `GET /docs` publishes
+the live tool schema. A bare `GET /mcp` returns `405`; protocol requests use
+`POST /mcp`. The server also exposes `find_papers`, `compare_leaderboard`, and
+`survey_task` prompts.
+
+## Test
+
+```bash
+uv run --project mcp_server pytest mcp_server/tests
+```
+
+The canonical hosted service is deployed as an immutable VPS component and
+published through `https://paperswithcode.co/mcp`. The
+`huggingface/paperswithcode-mcp` Docker Space remains an optional fallback; its
+container explicitly binds to `0.0.0.0`.

mcp_server/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: pwc-mcp
+description: "Papers With Code MCP tools for searching and reading AI/ML papers, discovering recent and trending research, finding related work and paper lineage, browsing tasks, methods, conferences, organizations, and frameworks, and inspecting benchmark leaderboards with model-size and metric filters through the public Papers With Code catalog. Use whenever the user asks to find papers, survey literature, compare research, inspect an arXiv paper, explore AI/ML taxonomy or conferences, discover benchmarks or state-of-the-art models, or mentions Papers With Code, the PwC MCP server, or paperswithcode.co/mcp."
+compatibility: "Requires an MCP client connected to https://paperswithcode.co/mcp with the Papers With Code tools available."
+---
+
+Generated for `pwc-mcp v0.2.7` and stock-client MCP protocol `2025-11-25`.
+
+The tools query the public [Papers With Code](https://paperswithcode.co) catalog
+anonymously and are read-only. Every tool runs the matching `pwc` CLI research
+command, and every research flag of that command is a tool parameter, so
+results match `pwc ... --json`. If live tool discovery and this skill disagree,
+the discovered tool schemas are authoritative.
+
+Every result carries `schema_version` and `data`, the complete CLI JSON payload
+for the call. Typed fields such as `items`, `paper`, `task`, `evaluations` are
+projections of `data`; read `data` when a projection lacks a detail. Use
+structured output directly for filtering, joining, or other schema-dependent
+processing.
+
+When the user identifies an author, prefer repeatable structured
+`list_papers` calls with the `authors` argument. Add `search` for stated topic
+terms and explicit `order_by: "date_published"` and `order_direction: "desc"`
+for newest or recent work; the default order is `trending`. Author references
+accept an exact normalized name, numeric ID, or `@HF_USERNAME`; multiple
+authors use AND semantics.
+
+Publication date ranges are inclusive: use `published_after: "YYYY-MM-DD"` and
+`published_before: "YYYY-MM-DD"` with `search_papers` or `list_papers`; the
+start date must not be later than the end date.
+
+Paper discovery results always include official implementation status and the
+total linked repository count. Use `has_official_implementation: true` with
+`search_papers` or `list_papers` to require a catalog-linked official
+repository; this filter fails closed if unconfirmed.
+
+Use `get_benchmark` with `max_parameters` to keep models at or below an
+inclusive parameter limit. It accepts values such as `"500M"`, `"1.5B"`, `"3B"`,
+and raw integers. Models without one consistent parameter count are excluded
+from constrained results. Combine `require_metrics`, `minimum_metrics`,
+`maximum_metrics`, `sort_metric`, and `pareto` to select leaderboard rows by
+metric; a metric the leaderboard does not report returns the unfiltered
+leaderboard with a `metric_note` naming the available metrics.
+
+`paper` accepts a modern or legacy arXiv ID, a numeric external-paper ID, an
+arXiv, Hugging Face, or Papers With Code URL, an exact paper title, or the
+short name before a title's colon ("MuseTalk"). Title matching is
+case-insensitive but exact; ambiguous titles fail with their matching IDs. When
+a paper is not indexed on Papers With Code, `get_paper_info`, `read_paper`, and
+`get_related_papers` return public Hugging Face Papers, arXiv, or Crossref (for
+DOIs and exact titles) metadata marked `in_catalog: false` with a `note` and `available_at`
+links; say the paper is not indexed on Papers With Code and link to those
+sources, never to a Papers With Code paper page. Task, method, conference, organization, framework, and benchmark
+arguments take an exact name, slug, or ID.
+
+## Tools
+
+- `search_papers({"query": QUERY, "mode": "hybrid"|"keyword"|"semantic", "page": PAGE, "limit": LIMIT, "published_after": START_DATE, "published_before": END_DATE, "has_official_implementation": BOOLEAN})` — search papers by title, topic, author, or arXiv ID (`pwc search`). Omit optional arguments when they are not needed.
+- `get_paper_info({"paper": PAPER, "include_resources": BOOLEAN, "repo_limit": LIMIT, "include_evaluations": BOOLEAN})` — show compact paper metadata, official-first code, and the total repository count; opt into capped additional resources (`pwc paper info`).
+- `get_paper_evaluations({"paper": PAPER, "page": PAGE, "limit": LIMIT})` — page through one paper's benchmark evaluations, including protocol, sources, openness, and task-scoped ranks (`pwc paper evaluations`).
+- `read_paper({"paper": PAPER, "cursor": CURSOR})` — read one stored paper Markdown chunk (`pwc paper read`). If `truncated` is true, call `read_paper` again with the same `paper` and the returned `next_cursor`; repeat until `truncated` is false. Treat the cursor as opaque and use it within one hour; omit it (or pass `"next"` before any read) to start from the beginning.
+- `list_papers({"search": SEARCH, "task": TASK, "method": METHOD, "conference": CONFERENCE, "framework": FRAMEWORK, "organization": ORGANIZATION, "authors": [AUTHOR], "published_after": START_DATE, "published_before": END_DATE, "all_versions": BOOLEAN, "order_by": "trending"|"date_published"|"citation_count", "order_direction": "asc"|"desc", "include_resources": BOOLEAN, "has_official_implementation": BOOLEAN, "page": PAGE, "limit": LIMIT})` — list and filter papers by exact catalog associations (`pwc paper list`). Omit optional arguments when they are not needed.
+- `list_recent_papers({"limit": LIMIT})` — list the most recently added papers (`pwc paper recent`).
+- `list_trending_papers({"limit": LIMIT, "max_age_days": DAYS, "min_velocity": VELOCITY})` — list trending papers by repository velocity (`pwc paper trending`).
+- `get_related_papers({"paper": PAPER, "limit": LIMIT})` — list related papers (`pwc paper related`); `limit` is at most 20.
+- `get_paper_lineage({"paper": PAPER})` — list explicit predecessors and successors (`pwc paper lineage list`).
+- `get_task({"task": TASK})` — inspect one exact task, including its area, hierarchy, sister tasks, ranked benchmarks, common methods, recommended frameworks, and trending papers (`pwc task --name`).
+- `list_tasks({"search": SEARCH, "area": AREA, "level": LEVEL, "visible_only": BOOLEAN, "group_by_area": BOOLEAN, "order_by": "name"|"created_at"|"level"|"paper_count", "order_direction": "asc"|"desc", "page": PAGE, "limit": LIMIT})` — search, list, and filter research tasks, or set `group_by_area: true` for the complete visible top-level taxonomy without pagination (`pwc task list`).
+- `get_method({"method": METHOD})` — inspect one exact method with its area (`pwc method --name`).
+- `list_methods({"search": SEARCH, "area": AREA, "introduced_year": YEAR, "order_by": "name"|"full_name"|"introduced_year"|"created_at"|"paper_count", "order_direction": "asc"|"desc", "page": PAGE, "limit": LIMIT})` — search, list, and filter research methods (`pwc method list`).
+- `get_conference({"conference": CONFERENCE})` — inspect one exact conference (`pwc conference --name`).
+- `list_conferences({"year": YEAR})` — list conferences with imported papers (`pwc conference list`).
+- `get_organization({"organization": ORGANIZATION})` — inspect one exact research organization (`pwc organization --name`).
+- `list_organizations({"featured_only": BOOLEAN})` — list research organizations (`pwc organization list`).
+- `get_framework({"framework": FRAMEWORK})` — inspect one exact research framework (`pwc framework --name`).
+- `list_frameworks({"domain": DOMAIN, "category": CATEGORY, "platform": PLATFORM})` — list research frameworks (`pwc framework list`).
+- `get_benchmark({"benchmark": BENCHMARK, "page": PAGE, "limit": LIMIT, "is_open": BOOLEAN, "max_parameters": SIZE, "require_metrics": [METRIC], "minimum_metrics": {METRIC: VALUE}, "maximum_metrics": {METRIC: VALUE}, "sort_metric": "METRIC:asc|desc", "pareto": ["METRIC:higher", "METRIC:lower"]})` — inspect one paginated benchmark leaderboard with model-size, metric threshold, sort, and Pareto selection (`pwc benchmark --name`). `matched_count` reports rows that satisfied the filters before pagination.
+- `list_benchmarks({"search": SEARCH, "task": TASK, "include_descendants": BOOLEAN, "minimum_evaluations": COUNT, "is_open": BOOLEAN, "group_by_area": BOOLEAN, "area": AREA, "benchmarks_per_task": COUNT, "order_by": "trending"|"name"|"full_name"|"created_at"|"paper_count", "order_direction": "asc"|"desc", "page": PAGE, "limit": LIMIT})` — list and filter benchmarks (`pwc benchmark list`). With `task`, results are ranked by trend unless `order_by` is set; `group_by_area` or `area` returns top benchmarks under each visible task.
+
+All page numbers start at 1. `limit` is between 1 and 25 and defaults to the
+CLI page size capped at 25. Follow `next_page` when the user asks for more
+results than one response contains; do not infer that a missing item does not
+exist until the relevant pages have been checked.
+
+The MCP server does not expose the standalone CLI's paper editing,
+authentication, skill installation, or version commands, and `pwc paper read`
+is served as `read_paper` chunks rather than one document.
+Do not invent equivalent tools. Use the separate `pwc` CLI only when it is
+available and the user needs one of those capabilities.
+
+## Research workflow
+
+1. Use `list_benchmarks({"task": TASK})` to discover active benchmarks, then
+   `get_benchmark({"benchmark": NAME})` to inspect a leaderboard. Add
+   `max_parameters` when model size is part of the request and `sort_metric`
+   or `minimum_metrics` when a specific metric matters.
+2. Use `get_paper_info({"paper": PAPER})` to inspect promising results. Its
+   response includes official-first code; use `get_paper_evaluations` to page
+   through its benchmark results.
+3. Use exact `list_papers` `authors`, `task`, `method`, `conference`,
+   `framework`, and `organization` arguments for known identities or catalog
+   associations. Combine them to require every association; do not substitute
+   a keyword search. Add `search` for title or abstract topic terms.
+4. Use `search_papers` for broader discovery, then `read_paper` for primary
+   evidence. Follow every returned continuation cursor needed for the user's
+   question.
+5. Expand the literature with `get_related_papers` and use
+   `get_paper_lineage` when model or method ancestry matters. Use `get_task`,
+   `get_method`, `list_conferences`, `list_organizations`, and
+   `list_frameworks` to orient within the taxonomy.
+6. Preserve paper titles, identifiers, and URLs so claims remain traceable.
+
+## Output and limits
+
+- Tool results use stable, versioned structured output with compact text
+  fallbacks. Prefer structured fields over parsing the text fallback.
+- Search mode is deterministic: `hybrid` is the default, matching
+  `pwc search`; `keyword` uses lexical retrieval alone and `semantic` uses
+  dense retrieval alone. Both `hybrid` and `semantic` count toward the semantic
+  search rate limit, so pass `mode: "keyword"` for exact terminology or when
+  that limit is close.
+- Catalog-filtered paper lists fail closed unless the server confirms every
+  requested filter; never treat results from an older server as filtered.
+  Parameter-filtered leaderboards fail closed unless the server confirms
+  parameter-filter support and every returned model satisfies the limit.
+- `read_paper` returns at most one 64 KiB chunk per call. A continuation stays
+  pinned to the resolved paper and content version; if the paper changes, start
+  reading again from the beginning.
+- The hosted service limits each client to 60 total requests and 10 semantic
+  or hybrid searches per minute, with at most four concurrent requests. Respect
+  retry metadata instead of trying to work around limits.
+- The tools contain no authentication, catalog mutation, ingestion,
+  publication, image, embedding, CRON, or infrastructure-maintenance
+  operations.

mcp_server/SPEC.md

@@ -0,0 +1,119 @@
+# 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`, 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.

mcp_server/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "pwc-mcp"
+version = "0.2.10"
+description = "Read-only Papers With Code MCP server"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = [
+  "mcp>=2.1,<3",
+  "pydantic>=2.11,<3",
+  "pwc-cli>=0.4.1,<0.5",
+  "starlette>=0.47,<1",
+  "uvicorn>=0.35,<1",
+]
+
+[project.scripts]
+pwc-mcp = "pwc_mcp.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pwc_mcp"]
+
+[tool.uv.sources]
+pwc-cli = {path = "../standalone_cli", editable = true}
+
+[dependency-groups]
+dev = ["httpx>=0.28,<1", "pytest>=8"]

mcp_server/space/README.md

@@ -0,0 +1,19 @@
+---
+title: Papers With Code MCP
+emoji: 📚
+colorFrom: yellow
+colorTo: blue
+sdk: docker
+app_port: 7860
+suggested_hardware: cpu-upgrade
+short_description: Read-only MCP access to the Papers With Code research catalog
+---
+
+# Papers With Code MCP
+
+Anonymous, read-only access to papers, tasks, methods, benchmarks, and
+leaderboards through Model Context Protocol.
+
+- MCP endpoint: `/mcp`
+- Health endpoint: `/health`
+- Source: <https://github.com/huggingface/pwc-cli>

mcp_server/src/pwc_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Read-only Papers With Code MCP server."""
+
+__version__ = "0.2.10"

mcp_server/src/pwc_mcp/app.py

@@ -0,0 +1,579 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import ipaddress
+import json
+import logging
+import os
+import re
+import secrets
+import threading
+import time
+from collections import defaultdict, deque
+
+import anyio.to_thread
+import uvicorn
+from mcp.server.transport_security import TransportSecuritySettings
+from pwc_cli.transport import ResponseError, TransportError
+from starlette.datastructures import Headers
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from pwc_mcp import __version__
+from pwc_mcp.catalog import CatalogClient
+from pwc_mcp.server import DEFAULT_SEARCH_MODE, TOOL_COMMANDS, Catalog, build_server
+
+LOGGER = logging.getLogger("pwc_mcp.requests")
+# MCP SDK diagnostics can include peer-supplied tool names and resource URIs.
+# OperationalTelemetryMiddleware is the server's sole request log surface.
+logging.getLogger("mcp").setLevel(logging.CRITICAL + 1)
+PROTOCOL_VERSION = "2025-11-25"
+EXPERIMENTAL_PROTOCOL_VERSION = "2026-07-28"
+MAX_REQUEST_BODY_SIZE = 2 * 1024 * 1024
+MAX_RESPONSE_BODY_SIZE = 2 * 1024 * 1024
+KNOWN_TOOLS = frozenset(TOOL_COMMANDS)
+KNOWN_PROTOCOLS = {
+    PROTOCOL_VERSION,
+    EXPERIMENTAL_PROTOCOL_VERSION,
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+}
+
+
+async def well_known_mcp(_request: Request) -> JSONResponse:
+    return JSONResponse(
+        {
+            "name": "Papers With Code",
+            "description": "Anonymous read-only AI research catalog",
+            "transport": {"type": "streamable-http", "url": "/mcp"},
+            "protocol_version": PROTOCOL_VERSION,
+            "supported_protocol_versions": sorted(KNOWN_PROTOCOLS, reverse=True),
+            "documentation_url": "https://paperswithcode.co/mcp/schema",
+            "setup_url": "https://paperswithcode.co/mcp",
+        }
+    )
+
+
+def _docs_schema(server) -> dict:
+    return {
+        "name": "Papers With Code MCP",
+        "version": __version__,
+        "protocol_version": PROTOCOL_VERSION,
+        "endpoint": "/mcp",
+        "tools": [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "inputSchema": tool.parameters,
+                "outputSchema": tool.output_schema,
+            }
+            for tool in server._tool_manager.list_tools()
+        ],
+    }
+
+
+class MCPMethodMiddleware:
+    """Reject a bare GET instead of opening an unbounded SSE response."""
+
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] == "http"
+            and scope.get("path") == "/mcp"
+            and scope.get("method") == "GET"
+        ):
+            response = JSONResponse(
+                {"error": "method_not_allowed", "allowed": ["POST"]},
+                status_code=405,
+                headers={"Allow": "POST"},
+            )
+            await response(scope, receive, send)
+            return
+        await self.app(scope, receive, send)
+
+
+# Hosted defaults. The first-party chat gateway names one identity per chat
+# session (see _client_address), so per-client limits protect fairness while
+# the global ceiling protects the process. Every value is overridable through
+# the environment for other deployments.
+DEFAULT_REQUEST_LIMIT = 60
+DEFAULT_SEMANTIC_LIMIT = 10
+DEFAULT_CONCURRENCY_LIMIT = 4
+DEFAULT_GLOBAL_CONCURRENCY_LIMIT = 128
+# anyio runs synchronous tool functions in a thread pool whose default size (40)
+# would silently cap concurrency below the global ceiling.
+MINIMUM_THREAD_TOKENS = 40
+
+
+def _int_env(name: str, default: int, *, maximum: int = 10_000) -> int:
+    value = os.environ.get(name)
+    if value is None or not value.strip():
+        return default
+    if not value.strip().isdigit() or not 1 <= int(value) <= maximum:
+        raise ValueError(f"{name} must be an integer between 1 and {maximum}")
+    return int(value)
+
+
+def thread_limiter_tokens(global_concurrency_limit: int) -> int:
+    return max(MINIMUM_THREAD_TOKENS, global_concurrency_limit)
+
+
+def _csv_env(name: str, default: list[str]) -> list[str]:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+class CatalogReadiness:
+    def __init__(self, catalog: CatalogClient | None, *, initially_ready: bool = False):
+        self.catalog = catalog
+        self.ready = initially_ready
+        self.probing = False
+        self.next_probe_at = 0.0
+        self.lock = threading.Lock()
+
+    def schedule(self) -> None:
+        if self.catalog is None:
+            return
+        now = time.monotonic()
+        with self.lock:
+            if self.probing or now < self.next_probe_at:
+                return
+            self.probing = True
+        asyncio.create_task(asyncio.to_thread(self._probe))
+
+    def _probe(self) -> None:
+        try:
+            assert self.catalog is not None
+            ready = self.catalog.check_readiness()
+        except (ResponseError, TransportError):
+            ready = False
+        with self.lock:
+            self.ready = ready
+            self.probing = False
+            self.next_probe_at = time.monotonic() + (30 if ready else 5)
+
+
+async def health(request: Request) -> JSONResponse:
+    readiness: CatalogReadiness = request.app.state.pwc_catalog_readiness
+    readiness.schedule()
+    ready = readiness.ready
+    return JSONResponse(
+        {
+            "status": "ok" if ready else "unavailable",
+            "service": "pwc-mcp",
+            "version": __version__,
+            "protocol": PROTOCOL_VERSION,
+        },
+        status_code=200 if ready else 503,
+    )
+
+
+# A first-party client on the same host (the chat gateway) may name the
+# rate-limit identity of a request, for example one hashed chat session. The
+# header counts only on a direct loopback connection that carries no proxy
+# header: nginx always adds X-Forwarded-For, so public traffic cannot use it.
+CLIENT_IDENTITY_HEADER = "x-pwc-mcp-client"
+CLIENT_IDENTITY = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
+
+
+def _client_address(scope: Scope, headers: Headers, trust_proxy_headers: bool) -> str:
+    client = scope.get("client")
+    direct_address = str(client[0]) if client else "unknown"
+    try:
+        trusted_hop = ipaddress.ip_address(direct_address).is_loopback
+    except ValueError:
+        trusted_hop = False
+    if trust_proxy_headers and trusted_hop:
+        forwarded = headers.get("x-forwarded-for")
+        if forwarded:
+            return forwarded.split(",", 1)[0].strip()
+        identity = headers.get(CLIENT_IDENTITY_HEADER, "")
+        if CLIENT_IDENTITY.fullmatch(identity):
+            return f"client:{identity}"
+    return direct_address
+
+
+class RequestBodyTooLarge(Exception):
+    pass
+
+
+class ResponseSizeLimitMiddleware:
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] != "http"
+            or scope.get("path") != "/mcp"
+            or scope.get("method") != "POST"
+        ):
+            await self.app(scope, receive, send)
+            return
+        messages: list[Message] = []
+        size = 0
+        oversized = False
+
+        async def capture(message: Message) -> None:
+            nonlocal size, oversized
+            if message["type"] == "http.response.body":
+                size += len(message.get("body", b""))
+                oversized = oversized or size > MAX_RESPONSE_BODY_SIZE
+            if not oversized:
+                messages.append(message)
+
+        await self.app(scope, receive, capture)
+        if oversized:
+            response = JSONResponse({"error": "response_too_large"}, status_code=503)
+            await response(scope, receive, send)
+            return
+        for message in messages:
+            await send(message)
+
+
+async def _body_and_replay(
+    receive: Receive, *, maximum_bytes: int
+) -> tuple[bytes, Receive]:
+    messages: list[Message] = []
+    chunks = []
+    size = 0
+    while True:
+        message = await receive()
+        messages.append(message)
+        if message["type"] != "http.request":
+            break
+        chunk = message.get("body", b"")
+        size += len(chunk)
+        if size > maximum_bytes:
+            raise RequestBodyTooLarge
+        chunks.append(chunk)
+        if not message.get("more_body", False):
+            break
+    pending = deque(messages)
+
+    async def replay() -> Message:
+        if pending:
+            return pending.popleft()
+        return await receive()
+
+    return b"".join(chunks), replay
+
+
+def _tool_and_semantic(headers: Headers, body: bytes) -> tuple[str | None, bool]:
+    header_tool = headers.get("mcp-name")
+    body_tool = None
+    mode = DEFAULT_SEARCH_MODE
+    try:
+        payload = json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        tool = header_tool if header_tool in KNOWN_TOOLS else None
+        return tool, False
+    if isinstance(payload, dict):
+        params = payload.get("params")
+        if isinstance(params, dict):
+            body_tool = (
+                params.get("name") if isinstance(params.get("name"), str) else None
+            )
+    if isinstance(payload, dict):
+        params = payload.get("params")
+        arguments = params.get("arguments") if isinstance(params, dict) else None
+        if isinstance(arguments, dict):
+            mode = arguments.get("mode", DEFAULT_SEARCH_MODE)
+    tool = body_tool or header_tool
+    tool = tool if tool in KNOWN_TOOLS else None
+    # Hybrid retrieval also runs the dense embedding search upstream.
+    return tool, tool == "search_papers" and mode in {"semantic", "hybrid"}
+
+
+def _protocol_label(headers: Headers) -> str:
+    value = headers.get("mcp-protocol-version")
+    if value is None:
+        return "legacy"
+    return value if value in KNOWN_PROTOCOLS else "unknown"
+
+
+class RateLimitMiddleware:
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        request_limit: int,
+        semantic_limit: int,
+        concurrency_limit: int,
+        global_concurrency_limit: int,
+        trust_proxy_headers: bool,
+        identity_limit: int = 10_000,
+    ):
+        self.app = app
+        self.request_limit = request_limit
+        self.semantic_limit = semantic_limit
+        self.concurrency_limit = concurrency_limit
+        self.global_concurrency_limit = global_concurrency_limit
+        self.trust_proxy_headers = trust_proxy_headers
+        self.identity_limit = identity_limit
+        self.key = secrets.token_bytes(32)
+        self.requests: dict[str, deque[float]] = defaultdict(deque)
+        self.semantic_requests: dict[str, deque[float]] = defaultdict(deque)
+        self.active: dict[str, int] = defaultdict(int)
+        self.lock = asyncio.Lock()
+        self.next_cleanup_at = 0.0
+        self.global_active = 0
+
+    def _identity(self, address: str) -> str:
+        return hashlib.blake2b(
+            address.encode(), key=self.key, digest_size=16
+        ).hexdigest()
+
+    @staticmethod
+    def _trim(values: deque[float], now: float) -> None:
+        while values and values[0] <= now - 60:
+            values.popleft()
+
+    def _purge_stale_identities(self, now: float) -> None:
+        for identity in list(self.requests):
+            requests = self.requests[identity]
+            semantic_requests = self.semantic_requests.get(identity)
+            self._trim(requests, now)
+            if semantic_requests is not None:
+                self._trim(semantic_requests, now)
+            if not requests and not semantic_requests and not self.active.get(identity):
+                self.requests.pop(identity, None)
+                self.semantic_requests.pop(identity, None)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            anyio.to_thread.current_default_thread_limiter().total_tokens = (
+                thread_limiter_tokens(self.global_concurrency_limit)
+            )
+        if (
+            scope["type"] != "http"
+            or scope.get("path") != "/mcp"
+            or scope.get("method") != "POST"
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        try:
+            body, replay = await _body_and_replay(
+                receive, maximum_bytes=MAX_REQUEST_BODY_SIZE
+            )
+        except RequestBodyTooLarge:
+            response = JSONResponse({"error": "request_too_large"}, status_code=413)
+            await response(scope, receive, send)
+            return
+        tool, semantic = _tool_and_semantic(headers, body)
+        scope.setdefault("state", {})["pwc_tool_name"] = tool
+        identity = self._identity(
+            _client_address(scope, headers, self.trust_proxy_headers)
+        )
+        now = time.monotonic()
+        limited = False
+        saturated = False
+        requests: deque[float] | None = None
+        semantic_requests: deque[float] | None = None
+        async with self.lock:
+            saturated = self.global_active >= self.global_concurrency_limit
+            if not saturated and (
+                identity not in self.requests
+                and len(self.requests) >= self.identity_limit
+            ):
+                if now >= self.next_cleanup_at:
+                    self._purge_stale_identities(now)
+                    self.next_cleanup_at = now + 5
+                limited = len(self.requests) >= self.identity_limit
+            if not limited and not saturated:
+                requests = self.requests[identity]
+                semantic_requests = self.semantic_requests[identity]
+                self._trim(requests, now)
+                self._trim(semantic_requests, now)
+                limited = (
+                    len(requests) >= self.request_limit
+                    or (semantic and len(semantic_requests) >= self.semantic_limit)
+                    or self.active[identity] >= self.concurrency_limit
+                )
+            if not limited and not saturated:
+                assert requests is not None
+                assert semantic_requests is not None
+                requests.append(now)
+                if semantic:
+                    semantic_requests.append(now)
+                self.active[identity] += 1
+                self.global_active += 1
+        if saturated:
+            response = JSONResponse(
+                {"error": "server_saturated"},
+                status_code=503,
+                headers={"Retry-After": "1"},
+            )
+            await response(scope, replay, send)
+            return
+        if limited:
+            response = JSONResponse(
+                {"error": "rate_limit_exceeded"},
+                status_code=429,
+                headers={"Retry-After": "60"},
+            )
+            await response(scope, replay, send)
+            return
+        try:
+            await self.app(scope, replay, send)
+        finally:
+            async with self.lock:
+                self.active[identity] -= 1
+                if self.active[identity] == 0:
+                    self.active.pop(identity, None)
+                self.global_active -= 1
+
+
+class OperationalTelemetryMiddleware:
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope.get("path") != "/mcp":
+            await self.app(scope, receive, send)
+            return
+        started = time.monotonic()
+        status = 500
+        size = 0
+
+        async def observe(message: Message) -> None:
+            nonlocal status, size
+            if message["type"] == "http.response.start":
+                status = int(message["status"])
+            elif message["type"] == "http.response.body":
+                size += len(message.get("body", b""))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, observe)
+        finally:
+            headers = Headers(scope=scope)
+            tool = scope.get("state", {}).get("pwc_tool_name")
+            if tool not in KNOWN_TOOLS:
+                tool = "unknown"
+            LOGGER.info(
+                "mcp_request tool=%s status=%s latency_ms=%s bytes=%s protocol=%s version=%s",
+                tool or "unknown",
+                status,
+                round((time.monotonic() - started) * 1000),
+                size,
+                _protocol_label(headers),
+                __version__,
+            )
+
+
+def create_app(
+    catalog: Catalog | None = None,
+    *,
+    allowed_hosts: list[str] | None = None,
+    allowed_origins: list[str] | None = None,
+    request_limit: int | None = None,
+    semantic_limit: int | None = None,
+    concurrency_limit: int | None = None,
+    global_concurrency_limit: int | None = None,
+    trust_proxy_headers: bool = True,
+) -> ASGIApp:
+    if request_limit is None:
+        request_limit = _int_env("PWC_MCP_REQUEST_LIMIT", DEFAULT_REQUEST_LIMIT)
+    if semantic_limit is None:
+        semantic_limit = _int_env("PWC_MCP_SEMANTIC_LIMIT", DEFAULT_SEMANTIC_LIMIT)
+    if concurrency_limit is None:
+        concurrency_limit = _int_env(
+            "PWC_MCP_CONCURRENCY_LIMIT", DEFAULT_CONCURRENCY_LIMIT
+        )
+    if global_concurrency_limit is None:
+        global_concurrency_limit = _int_env(
+            "PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", DEFAULT_GLOBAL_CONCURRENCY_LIMIT
+        )
+    hosts = allowed_hosts or _csv_env(
+        "PWC_MCP_ALLOWED_HOSTS",
+        [
+            "huggingface-paperswithcode-mcp.hf.space",
+            "localhost:*",
+            "127.0.0.1:*",
+        ],
+    )
+    origins = allowed_origins or _csv_env(
+        "PWC_MCP_ALLOWED_ORIGINS",
+        ["https://chatgpt.com", "https://claude.ai"],
+    )
+    if "*" in origins:
+        raise ValueError("PWC_MCP_ALLOWED_ORIGINS must not contain a wildcard")
+    catalog_client = CatalogClient() if catalog is None else None
+    resolved_catalog = catalog or catalog_client
+    assert resolved_catalog is not None
+    server = build_server(resolved_catalog)
+    app = server.streamable_http_app(
+        streamable_http_path="/mcp",
+        json_response=True,
+        stateless_http=True,
+        max_request_body_size=MAX_REQUEST_BODY_SIZE,
+        host="0.0.0.0",
+        transport_security=TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=hosts,
+            allowed_origins=origins,
+        ),
+    )
+    app.routes.insert(0, Route("/health", health, methods=["GET"]))
+    schema = _docs_schema(server)
+
+    async def docs(_request: Request) -> JSONResponse:
+        return JSONResponse(schema)
+
+    app.routes.insert(1, Route("/docs", docs, methods=["GET"]))
+    app.routes.insert(2, Route("/.well-known/mcp", well_known_mcp, methods=["GET"]))
+    app.state.pwc_catalog_readiness = CatalogReadiness(
+        catalog_client,
+        initially_ready=catalog is not None,
+    )
+    wrapped: ASGIApp = RateLimitMiddleware(
+        app,
+        request_limit=request_limit,
+        semantic_limit=semantic_limit,
+        concurrency_limit=concurrency_limit,
+        global_concurrency_limit=global_concurrency_limit,
+        trust_proxy_headers=trust_proxy_headers,
+    )
+    wrapped = MCPMethodMiddleware(wrapped)
+    wrapped = ResponseSizeLimitMiddleware(wrapped)
+    wrapped = OperationalTelemetryMiddleware(wrapped)
+    return CORSMiddleware(
+        wrapped,
+        allow_origins=origins,
+        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_headers=[
+            "authorization",
+            "content-type",
+            "mcp-protocol-version",
+            "mcp-method",
+            "mcp-name",
+            "mcp-session-id",
+        ],
+        expose_headers=["mcp-session-id", "retry-after"],
+    )
+
+
+def main() -> None:
+    logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"))
+    uvicorn.run(
+        create_app(),
+        host=os.environ.get("PWC_MCP_HOST", "127.0.0.1"),
+        port=int(os.environ.get("PORT", "7860")),
+        proxy_headers=False,
+        access_log=False,
+    )
+
+
+if __name__ == "__main__":
+    main()

mcp_server/src/pwc_mcp/catalog.py

@@ -0,0 +1,564 @@
+from __future__ import annotations
+
+import re
+import threading
+from difflib import SequenceMatcher
+import time
+from collections import OrderedDict
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.parse import quote, urlparse
+
+from pwc_cli import queries
+from pwc_cli.transport import (
+    Client,
+    HTTPStatusError,
+    Response,
+    ResponseError,
+    TransportError,
+)
+
+PAPER_ID = re.compile(r"(?:\d{4}\.\d{4,5}|[a-z][a-z0-9.-]*/\d{7}|\d+)", re.IGNORECASE)
+ARXIV_VERSION = re.compile(r"v\d+$", re.IGNORECASE)
+CONTENT_VERSION = re.compile(r"[0-9a-f]{64}")
+MARKDOWN_CHUNK_BYTES = 65_536
+MARKDOWN_CACHE_ENTRIES = 256
+MARKDOWN_CACHE_BYTES = 16 * 1024 * 1024
+MARKDOWN_CACHE_SECONDS = 3600
+PUBLIC_PAPER_CACHE_SECONDS = 3600
+
+
+@dataclass(frozen=True)
+class PublicPaperMiss:
+    """Why the public-metadata API returned no record.
+
+    ``identifier``: no public source knows the ID, DOI, or URL. ``title``: no
+    arXiv or Crossref paper has exactly that title. ``unsupported``: neither an
+    identifier nor a searchable title. ``unavailable``: the lookup failed.
+    """
+
+    reason: str
+# Search and paper listings change quickly; taxonomy is stable; the rest sits
+# between (SPEC.md: one minute, ten minutes, and five minutes respectively).
+VOLATILE_PATHS = frozenset(
+    {"papers/", "papers/search", "papers/recent", "papers/trending"}
+)
+TAXONOMY_PREFIXES = (
+    "tasks/",
+    "methods/",
+    "areas/",
+    "conferences/",
+    "organizations/",
+    "frameworks/",
+)
+
+
+def cache_ttl(path: str) -> int:
+    if path in VOLATILE_PATHS:
+        return 60
+    if path.startswith(TAXONOMY_PREFIXES):
+        return 600
+    return 300
+
+
+@dataclass(frozen=True)
+class PaperMarkdownChunk:
+    paper: str
+    source: str
+    markdown: str
+    content_version: str
+    next_offset: int | None
+
+    @property
+    def truncated(self) -> bool:
+        return self.next_offset is not None
+
+
+class PaperVersionMismatchError(ResponseError):
+    pass
+
+
+class Transport(Protocol):
+    def get(
+        self, path: str, params: dict[str, object | None] | None = None
+    ) -> Response: ...
+
+
+def _freeze(value: object) -> object:
+    if isinstance(value, dict):
+        return tuple(sorted((key, _freeze(item)) for key, item in value.items()))
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def normalize_title(value: object) -> str:
+    return " ".join(re.findall(r"[a-z0-9]+", str(value or "").casefold()))
+
+
+def short_name(title: object) -> str:
+    """The name before a title's colon: "MuseTalk" for "MuseTalk: Real-Time ..."."""
+    text = str(title or "")
+    return normalize_title(text.split(":", 1)[0]) if ":" in text else ""
+
+
+# A near match tolerates a typo or variant spelling in a full title
+# ("Heterogeneous" for BEIR's "Heterogenous"), never a short name.
+NEAR_TITLE_MIN_CHARS = 24
+NEAR_TITLE_MIN_RATIO = 0.95
+
+
+def near_title(title: str, target: str) -> bool:
+    """Whether two normalized titles differ only by a small spelling change.
+
+    Numbers must agree, so a sequel or another year's edition never matches.
+    """
+    if len(target) < NEAR_TITLE_MIN_CHARS or title == target:
+        return False
+    if re.findall(r"\d+", title) != re.findall(r"\d+", target):
+        return False
+    return SequenceMatcher(None, title, target).ratio() >= NEAR_TITLE_MIN_RATIO
+
+class _TTLCache:
+    def __init__(self, maximum: int = 256):
+        self.maximum = maximum
+        self._values: OrderedDict[object, tuple[float, object]] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: object) -> object | None:
+        now = time.monotonic()
+        with self._lock:
+            cached = self._values.get(key)
+            if cached is None:
+                return None
+            expires_at, value = cached
+            if expires_at <= now:
+                del self._values[key]
+                return None
+            self._values.move_to_end(key)
+            return value
+
+    def put(self, key: object, value: object, ttl_seconds: int) -> None:
+        with self._lock:
+            self._values[key] = (time.monotonic() + ttl_seconds, value)
+            self._values.move_to_end(key)
+            while len(self._values) > self.maximum:
+                self._values.popitem(last=False)
+
+
+class _MarkdownChunkCache:
+    def __init__(self):
+        self._values: OrderedDict[object, tuple[float, int, PaperMarkdownChunk]] = (
+            OrderedDict()
+        )
+        self._bytes = 0
+        self._lock = threading.Lock()
+
+    def get(self, key: object) -> PaperMarkdownChunk | None:
+        now = time.monotonic()
+        with self._lock:
+            cached = self._values.get(key)
+            if cached is None:
+                return None
+            expires_at, size, value = cached
+            if expires_at <= now:
+                self._bytes -= size
+                del self._values[key]
+                return None
+            self._values.move_to_end(key)
+            return value
+
+    def put(self, key: object, value: PaperMarkdownChunk) -> None:
+        size = len(value.markdown.encode("utf-8"))
+        if size > MARKDOWN_CACHE_BYTES:
+            return
+        with self._lock:
+            previous = self._values.pop(key, None)
+            if previous is not None:
+                self._bytes -= previous[1]
+            self._values[key] = (
+                time.monotonic() + MARKDOWN_CACHE_SECONDS,
+                size,
+                value,
+            )
+            self._bytes += size
+            while (
+                len(self._values) > MARKDOWN_CACHE_ENTRIES
+                or self._bytes > MARKDOWN_CACHE_BYTES
+            ):
+                _, (_, removed_size, _) = self._values.popitem(last=False)
+                self._bytes -= removed_size
+
+
+class CatalogClient:
+    """Typed, cached catalog operations shared by every MCP tool."""
+
+    def __init__(self, transport: Transport | None = None):
+        self.transport = transport or Client(timeout=25)
+        self.cache = _TTLCache()
+        self.markdown_cache = _MarkdownChunkCache()
+
+    def _response(
+        self,
+        path: str,
+        params: Mapping[str, object | None] | None = None,
+        *,
+        ttl: int,
+    ) -> Response:
+        key = ("response", path, _freeze(dict(params or {})))
+        cached = self.cache.get(key)
+        if isinstance(cached, Response):
+            return cached
+        response = self.transport.get(path, dict(params or {}))
+        self.cache.put(key, response, ttl)
+        return response
+
+    def _json(
+        self,
+        path: str,
+        params: dict[str, object | None] | None = None,
+        *,
+        ttl: int,
+    ) -> dict[str, Any]:
+        payload = self._response(path, params, ttl=ttl).json()
+        if not isinstance(payload, dict):
+            raise ResponseError("API returned an unexpected response shape")
+        return payload
+
+    def check_readiness(self) -> bool:
+        response = self.transport.get("tasks/", {"page": 1, "page_size": 1})
+        payload = response.json()
+        if not isinstance(payload, dict):
+            return False
+        rows = payload.get("results")
+        if rows is None:
+            rows = payload.get("items")
+        return isinstance(rows, list)
+
+    def _text(self, path: str, *, ttl: int) -> str:
+        key = ("text", path)
+        cached = self.cache.get(key)
+        if isinstance(cached, str):
+            return cached
+        response = self.transport.get(path)
+        if response.headers.get("x-pwc-truncated") == "1":
+            raise ResponseError(
+                "Papers API returned incomplete Markdown; continuation is unavailable"
+            )
+        value = response.body.decode("utf-8", errors="replace")
+        self.cache.put(key, value, ttl)
+        return value
+
+    @staticmethod
+    def _rows(payload: dict[str, Any]) -> list[dict[str, Any]]:
+        values = payload.get("results")
+        if values is None:
+            values = payload.get("items")
+        # An empty list is a valid (empty) result, not a missing list.
+        if not isinstance(values, list):
+            raise ResponseError("API response did not contain a result list")
+        return [item for item in values if isinstance(item, dict)]
+
+    @staticmethod
+    def _paper_from_url(reference: str) -> str | None:
+        parsed = urlparse(reference)
+        if parsed.scheme not in {"http", "https"}:
+            return None
+        parts = [part for part in parsed.path.split("/") if part]
+        candidate = None
+        if (
+            parsed.netloc.casefold() in {"arxiv.org", "www.arxiv.org"}
+            and len(parts) >= 2
+        ):
+            if parts[0] in {"abs", "pdf"}:
+                candidate = "/".join(parts[1:])
+        elif parsed.netloc.casefold() == "huggingface.co" and len(parts) >= 2:
+            if parts[0] == "papers":
+                candidate = parts[1]
+        elif (
+            parsed.netloc.casefold()
+            in {
+                "paperswithcode.co",
+                "www.paperswithcode.co",
+            }
+            and len(parts) >= 2
+            and parts[0] == "paper"
+        ):
+            candidate = parts[1]
+        if candidate is None:
+            return None
+        candidate = candidate.removesuffix(".pdf")
+        return ARXIV_VERSION.sub("", candidate)
+
+    def _resolve_paper(self, reference: str) -> str:
+        candidate = reference.strip()
+        if not candidate:
+            raise ResponseError("Paper reference cannot be empty")
+        from_url = self._paper_from_url(candidate)
+        slug_from_url = None
+        if from_url:
+            candidate = from_url
+            parsed = urlparse(reference)
+            if parsed.netloc.casefold() in {
+                "paperswithcode.co",
+                "www.paperswithcode.co",
+            }:
+                slug_from_url = candidate.casefold()
+        elif urlparse(candidate).scheme in {"http", "https"}:
+            # A DOI, publisher, or venue URL is never an exact title; searching
+            # it would page through empty results before failing anyway.
+            raise ResponseError(
+                f"Paper URL not supported: {candidate}; only arXiv, Hugging Face, "
+                "and Papers With Code URLs resolve"
+            )
+        candidate = ARXIV_VERSION.sub("", candidate)
+        if PAPER_ID.fullmatch(candidate):
+            if candidate.isdigit():
+                return self._canonical_paper_id(candidate)
+            return candidate
+        query = candidate.replace("-", " ") if slug_from_url else candidate
+        target = " ".join(candidate.split()).casefold()
+        # The keyword search treats a quoted query as one phrase, so an exact
+        # title comes back in a single small page even when its words are
+        # common ("Attention Is All You Need" has over a thousand keyword
+        # hits). The plain query remains the fallback for titles the phrase
+        # parser cannot express.
+        phrase = '"' + " ".join(query.replace('"', " ").split()) + '"'
+        exact, named, near, exhausted = self._exact_title_matches(
+            phrase, target, slug_from_url
+        )
+        if not exact:
+            exact, more_named, more_near, exhausted = self._exact_title_matches(
+                query, target, slug_from_url
+            )
+            named = named or more_named
+            near = near or more_near
+        if not exact and not slug_from_url:
+            # Agents name a paper by the short name before its title's colon
+            # ("MuseTalk" for "MuseTalk: Real-Time ..."), or misspell one word
+            # of a full title; a unique such match resolves.
+            exact = named or near
+        if len(exact) == 1:
+            return next(iter(exact))
+        if exact:
+            choices = "; ".join(
+                f"{item.get('title')} ({paper})" for paper, item in exact.items()
+            )
+            raise ResponseError(f"Paper title is ambiguous: {candidate}; {choices}")
+        if not exhausted:
+            raise ResponseError("Too many results to resolve paper title safely")
+        raise ResponseError(f"Paper title not found: {candidate}")
+
+    def _exact_title_matches(
+        self, query: str, target: str, slug_from_url: str | None
+    ) -> tuple[
+        dict[str, dict[str, Any]], dict[str, dict[str, Any]], dict[str, dict[str, Any]], bool
+    ]:
+        """Collect papers whose title (or slug) equals the target.
+
+        Returns the matches, the papers whose short name before a title colon
+        equals the target, the papers whose title is a near match (see
+        `near_title`), and whether the search was read to its end within the
+        page budget; an unexhausted search with no match is inconclusive.
+        """
+        exact: dict[str, dict[str, Any]] = {}
+        named: dict[str, dict[str, Any]] = {}
+        near: dict[str, dict[str, Any]] = {}
+        target_name = normalize_title(target)
+        page = 1
+        while page <= 10:
+            payload = self._json(
+                "papers/search",
+                {"q": query, "page": page, "page_size": 100, "mode": "keyword"},
+                ttl=60,
+            )
+            for item in self._rows(payload):
+                paper = str(item.get("arxiv_id") or item.get("id") or "")
+                title = " ".join(str(item.get("title") or "").split()).casefold()
+                item_slug = str(item.get("slug") or "").casefold()
+                if not item_slug:
+                    item_slug = re.sub(r"[^a-z0-9]+", "-", title).strip("-")
+                if paper and (
+                    title == target or (slug_from_url and item_slug == slug_from_url)
+                ):
+                    exact.setdefault(paper, item)
+                elif paper and target_name and short_name(item.get("title")) == target_name:
+                    named.setdefault(paper, item)
+                elif paper and near_title(normalize_title(title), target_name):
+                    near.setdefault(paper, item)
+            next_page = payload.get("next_page")
+            if not isinstance(next_page, int) or next_page <= page:
+                return exact, named, near, True
+            page = next_page
+        return exact, named, near, False
+
+    def _canonical_paper_id(self, catalog_id: str) -> str:
+        """Prefer the arXiv ID for a numeric catalog ID so every route accepts it.
+
+        The Markdown read route stores arXiv papers under their arXiv ID and
+        only external papers under the numeric ID; list tools hand out numeric
+        IDs for both, so a bare numeric reference cannot tell them apart.
+        """
+        path = f"papers/{quote(catalog_id, safe='')}"
+        record = self._json(path, ttl=cache_ttl(path))
+        arxiv_id = record.get("arxiv_id")
+        if isinstance(arxiv_id, str) and arxiv_id.strip():
+            return ARXIV_VERSION.sub("", arxiv_id.strip())
+        return catalog_id
+
+    def _paper_exists(self, reference: str) -> bool:
+        path = f"papers/{quote(reference, safe='.')}"
+        try:
+            self._json(path, ttl=cache_ttl(path))
+        except HTTPStatusError as error:
+            if error.status == 404:
+                return False
+            raise
+        return True
+
+    def resolve_paper(self, paper: str) -> str:
+        return self._resolve_paper(paper)
+
+    def public_paper(self, reference: str) -> dict[str, Any] | PublicPaperMiss:
+        """The public-metadata API's record for a catalog miss, or why none.
+
+        The API resolves an arXiv ID or URL, Hugging Face paper URL, DOI, or
+        catalog ID against the catalog first, then Hugging Face Papers, arXiv,
+        or Crossref. It rejects anything else (400), which is then looked up
+        as an exact title on arXiv and Crossref; a record found that way
+        carries ``requested_title``. Lookups are best effort: a failure is an
+        ``unavailable`` miss, and only definitive misses are cached.
+        """
+        reference = reference.strip()
+        key = ("public-paper", reference)
+        cached = self.cache.get(key)
+        if isinstance(cached, (dict, PublicPaperMiss)):
+            return cached
+        # The route takes the reference as a path, slashes included (DOIs, URLs).
+        result = self._public_metadata(
+            f"papers/{quote(reference, safe='/:')}/public-metadata",
+            None,
+            PublicPaperMiss("identifier"),
+        )
+        if result == PublicPaperMiss("unsupported"):
+            result = self._public_metadata(
+                "papers/public-metadata/search",
+                {"title": reference},
+                PublicPaperMiss("title"),
+            )
+            if isinstance(result, dict):
+                result = {**result, "requested_title": reference}
+        if result != PublicPaperMiss("unavailable"):
+            self.cache.put(key, result, PUBLIC_PAPER_CACHE_SECONDS)
+        return result
+
+    def _public_metadata(
+        self, path: str, params: dict[str, Any] | None, not_found: PublicPaperMiss
+    ) -> dict[str, Any] | PublicPaperMiss:
+        try:
+            value = self.transport.get(path, params).json()
+        except HTTPStatusError as error:
+            if error.status == 404:
+                return not_found
+            # 429 and 503 are transient.
+            return PublicPaperMiss("unsupported" if error.status == 400 else "unavailable")
+        except (ResponseError, TransportError):
+            return PublicPaperMiss("unavailable")
+        if not isinstance(value, dict) or not value.get("title"):
+            return PublicPaperMiss("unavailable")
+        return value
+
+    def read_paper_chunk(
+        self,
+        paper: str,
+        *,
+        offset: int = 0,
+        content_version: str | None = None,
+        limit: int = MARKDOWN_CHUNK_BYTES,
+        resolved: bool = False,
+    ) -> PaperMarkdownChunk:
+        reference = paper if resolved else self._resolve_paper(paper)
+        source = "external" if reference.isdigit() else "arxiv"
+        cache_key = (reference, content_version, offset, limit)
+        if content_version is not None:
+            cached = self.markdown_cache.get(cache_key)
+            if cached is not None:
+                return cached
+        try:
+            response = self.transport.get(
+                f"research/papers/{quote(reference, safe='.')}/read",
+                {
+                    "offset": offset,
+                    "limit": limit,
+                    "content_version": content_version,
+                },
+            )
+        except HTTPStatusError as error:
+            if error.status == 409:
+                raise PaperVersionMismatchError(
+                    "Paper Markdown changed; restart reading from the beginning"
+                ) from error
+            if error.status == 404 and not self._paper_exists(reference):
+                raise ResponseError(f"Paper not found: {reference}") from error
+            raise
+
+        returned_version = response.headers.get("x-pwc-content-version", "")
+        truncated = response.headers.get("x-pwc-truncated")
+        next_text = response.headers.get("x-pwc-next-offset")
+        try:
+            markdown = response.body.decode("utf-8")
+            next_offset = int(next_text) if next_text is not None else None
+        except (UnicodeDecodeError, ValueError) as error:
+            raise ResponseError(
+                "Papers API returned an invalid Markdown chunk"
+            ) from error
+        if (
+            CONTENT_VERSION.fullmatch(returned_version) is None
+            or truncated not in {"0", "1"}
+            or (content_version is not None and returned_version != content_version)
+            or (truncated == "1" and next_offset is None)
+            or (truncated == "0" and next_offset is not None)
+            or (next_offset is not None and next_offset <= offset)
+            or (next_offset is not None and next_offset - offset != len(response.body))
+        ):
+            detail = (
+                "Papers API Markdown offset did not advance"
+                if next_offset is not None and next_offset <= offset
+                else "Papers API returned an invalid Markdown chunk"
+            )
+            raise ResponseError(detail)
+        result = PaperMarkdownChunk(
+            paper=reference,
+            source=source,
+            markdown=markdown,
+            content_version=returned_version,
+            next_offset=next_offset,
+        )
+        self.markdown_cache.put((reference, returned_version, offset, limit), result)
+        return result
+
+    def query(self, command: tuple[str, ...], options: Mapping[str, Any]) -> Any:
+        """Run one read-only ``pwc`` command in-process against the cached catalog.
+
+        Paper references are resolved first so URLs, legacy IDs, and exact
+        titles behave exactly as they do for ``read_paper``; the CLI then
+        receives the canonical identifier and applies its own validation,
+        fail-closed filter checks, and JSON payload shape.
+        """
+        resolved = dict(options)
+        if resolved.get("paper") is not None:
+            resolved["paper"] = self._resolve_paper(str(resolved["paper"]))
+        return queries.query(tuple(command), resolved, _CachedTransport(self))
+
+
+class _CachedTransport:
+    """``pwc_cli.transport.Client`` stand-in that serves CLI handlers from the cache."""
+
+    def __init__(self, catalog: CatalogClient):
+        self.catalog = catalog
+
+    def get(
+        self, path: str, params: Mapping[str, object | None] | None = None
+    ) -> Response:
+        return self.catalog._response(path, params, ttl=cache_ttl(path))

mcp_server/src/pwc_mcp/cursors.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+CURSOR_SCHEMA_VERSION = 1
+CURSOR_LIFETIME_SECONDS = 3600
+MAX_CURSOR_BYTES = 2048
+MAX_CHUNK_BYTES = 65_536
+_CONTENT_VERSION = re.compile(r"[0-9a-f]{64}")
+_PAPER_ID = re.compile(r"(?:\d{4}\.\d{4,5}|\d{1,20})")
+
+
+class CursorReferenceMismatch(ValueError):
+    """A valid cursor whose paper reference differs from the one supplied.
+
+    The caller may still honour it when the new reference resolves to the
+    cursor's paper (an agent that started from an arXiv ID and continues with
+    the numeric catalog ID, say).
+    """
+
+    def __init__(self, state: CursorState) -> None:
+        super().__init__(
+            "invalid continuation cursor: it belongs to another paper reference"
+        )
+        self.state = state
+
+
+@dataclass(frozen=True)
+class CursorState:
+    reference: str
+    paper: str
+    source: str
+    content_version: str
+    offset: int
+    limit: int
+    expires_at: int
+
+
+def _b64encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode().rstrip("=")
+
+
+def _b64decode(value: str) -> bytes:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+
+
+def _key_id(secret: bytes) -> str:
+    return hashlib.sha256(secret).hexdigest()[:16]
+
+
+class CursorCodec:
+    def __init__(
+        self,
+        current_secret: str,
+        *,
+        previous_secret: str | None = None,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        if not current_secret:
+            raise ValueError("current cursor secret is required")
+        current = current_secret.encode()
+        self._current_id = _key_id(current)
+        self._keys = {self._current_id: current}
+        if previous_secret:
+            previous = previous_secret.encode()
+            self._keys[_key_id(previous)] = previous
+        self._now = now
+
+    def encode(self, state: CursorState) -> str:
+        now = int(self._now())
+        if not self._valid_state(state) or not (
+            now < state.expires_at <= now + CURSOR_LIFETIME_SECONDS
+        ):
+            raise ValueError("invalid continuation cursor")
+        payload = {
+            "v": CURSOR_SCHEMA_VERSION,
+            "ref": state.reference,
+            "paper": state.paper,
+            "source": state.source,
+            "version": state.content_version,
+            "offset": state.offset,
+            "limit": state.limit,
+            "kid": self._current_id,
+            "exp": state.expires_at,
+        }
+        encoded = _b64encode(
+            json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+        )
+        signature = hmac.digest(self._keys[self._current_id], encoded.encode(), "sha256")
+        token = f"{encoded}.{_b64encode(signature)}"
+        if len(token) > MAX_CURSOR_BYTES:
+            raise ValueError("invalid continuation cursor")
+        return token
+
+    def decode(self, token: str, *, reference: str) -> CursorState:
+        try:
+            if not token or len(token) > MAX_CURSOR_BYTES:
+                raise ValueError
+            encoded, signature_text = token.split(".", 1)
+            raw = _b64decode(encoded)
+            if len(raw) > MAX_CURSOR_BYTES:
+                raise ValueError
+            payload = json.loads(raw)
+            if not isinstance(payload, dict):
+                raise TypeError
+            key_id = payload.get("kid")
+            if not isinstance(key_id, str):
+                raise TypeError
+            secret = self._keys.get(key_id)
+            if secret is None:
+                raise ValueError
+            supplied = _b64decode(signature_text)
+            expected = hmac.digest(secret, encoded.encode(), "sha256")
+            if not hmac.compare_digest(supplied, expected):
+                raise ValueError
+            state = CursorState(
+                reference=payload["ref"],
+                paper=payload["paper"],
+                source=payload["source"],
+                content_version=payload["version"],
+                offset=payload["offset"],
+                limit=payload["limit"],
+                expires_at=payload["exp"],
+            )
+            if (
+                payload.get("v") != CURSOR_SCHEMA_VERSION
+                or set(payload)
+                != {
+                    "v",
+                    "ref",
+                    "paper",
+                    "source",
+                    "version",
+                    "offset",
+                    "limit",
+                    "kid",
+                    "exp",
+                }
+                or not self._valid_state(state)
+            ):
+                raise ValueError
+            if state.expires_at <= int(self._now()):
+                raise TimeoutError
+            if state.reference != reference.strip():
+                raise CursorReferenceMismatch(state)
+            return state
+        except TimeoutError as error:
+            raise ValueError("expired continuation cursor") from error
+        except CursorReferenceMismatch:
+            raise
+        except (
+            ValueError,
+            TypeError,
+            KeyError,
+            json.JSONDecodeError,
+            UnicodeDecodeError,
+            binascii.Error,
+        ) as error:
+            raise ValueError("invalid continuation cursor") from error
+
+    @staticmethod
+    def _valid_state(state: CursorState) -> bool:
+        return (
+            isinstance(state.reference, str)
+            and 1 <= len(state.reference) <= 500
+            and state.reference == state.reference.strip()
+            and isinstance(state.paper, str)
+            and _PAPER_ID.fullmatch(state.paper) is not None
+            and state.source in {"arxiv", "external"}
+            and (state.source == "external") == state.paper.isdigit()
+            and isinstance(state.content_version, str)
+            and _CONTENT_VERSION.fullmatch(state.content_version) is not None
+            and isinstance(state.offset, int)
+            and not isinstance(state.offset, bool)
+            and 1 <= state.offset <= 2**63 - 1
+            and isinstance(state.limit, int)
+            and not isinstance(state.limit, bool)
+            and 1 <= state.limit <= MAX_CHUNK_BYTES
+            and isinstance(state.expires_at, int)
+            and not isinstance(state.expires_at, bool)
+        )

mcp_server/src/pwc_mcp/models.py

@@ -0,0 +1,585 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OutputModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+def _absolute_url(value: object) -> str | None:
+    if not value:
+        return None
+    url = str(value)
+    return f"https://paperswithcode.co{url}" if url.startswith("/") else url
+
+
+class QueryResult(OutputModel):
+    """The exact ``data`` document that ``pwc <command> --json`` prints."""
+
+    schema_version: Literal["v1"] = "v1"
+    data: Any = Field(
+        default=None,
+        description="Complete CLI JSON payload for this call; typed fields are projections of it.",
+    )
+
+
+class PaperSummary(OutputModel):
+    id: str
+    arxiv_id: str | None = None
+    title: str
+    authors: list[str]
+    published: str | None = None
+    citation_count: int | None = None
+    url: str | None = None
+    has_official_implementation: bool = Field(
+        description=(
+            "True when the catalog marks at least one linked repository as the "
+            "paper's official implementation; this is not an independent code audit."
+        )
+    )
+    code_repository_count: int
+
+
+class PaperLink(OutputModel):
+    label: str
+    url: str
+    kind: str | None = None
+
+
+AVAILABLE_AT = (
+    "Where a paper outside the catalog can be read (abstract page, PDF, Hugging "
+    "Face Papers, DOI, code); link to these, not to a Papers With Code paper page."
+)
+
+
+class PaperPage(QueryResult):
+    items: list[PaperSummary]
+    next_page: int | None = None
+    note: str | None = Field(
+        default=None,
+        description="Set when the requested paper is not in the catalog and the items are a search fallback.",
+    )
+    available_at: list[PaperLink] | None = Field(default=None, description=AVAILABLE_AT)
+
+
+class CatalogReference(OutputModel):
+    id: str
+    name: str
+    slug: str | None = None
+
+
+class RepositoryReference(OutputModel):
+    url: str
+    is_official: bool
+
+
+class XThreadReference(OutputModel):
+    url: str
+    author: str
+    handle: str
+
+
+class PaperDetail(OutputModel):
+    id: str
+    arxiv_id: str | None = None
+    title: str
+    abstract: str | None = None
+    authors: list[str]
+    published: str | None = None
+    citation_count: int | None = None
+    url: str | None = None
+    pdf_url: str | None = None
+    code_repository_count: int
+    tasks: list[CatalogReference]
+    methods: list[CatalogReference]
+    repositories: list[RepositoryReference]
+    project_pages: list[str]
+    hf_models: list[str] = []
+    hf_datasets: list[str] = []
+    hf_spaces: list[str] = []
+    x_threads: list[XThreadReference] = []
+
+
+class PaperEvaluation(OutputModel):
+    id: str
+    benchmark: str | None = None
+    task: str | None = None
+    model_name: str
+    harness: str | None = None
+    metrics: dict[str, float | int | str | None]
+    best_metric: str | None = None
+    best_rank: int | None = None
+    is_open: bool
+    num_parameters: int | None = None
+    source_url: str | None = None
+
+
+class PaperInfoResult(QueryResult):
+    paper: PaperDetail
+    evaluation_count: int | None = None
+    evaluations: list[PaperEvaluation] | None = None
+    in_catalog: bool = Field(
+        default=True,
+        description="False when the paper is not indexed on Papers With Code; the metadata then comes from public Hugging Face Papers, arXiv, or Crossref records.",
+    )
+    note: str | None = None
+    available_at: list[PaperLink] | None = Field(default=None, description=AVAILABLE_AT)
+
+
+class PaperReadResult(OutputModel):
+    schema_version: Literal["v1"] = "v1"
+    paper: str
+    markdown: str
+    truncated: bool
+    next_cursor: str | None = None
+    in_catalog: bool = Field(
+        default=True,
+        description="False when the paper is not indexed on Papers With Code; markdown then holds public metadata and the abstract, not the full text.",
+    )
+    available_at: list[PaperLink] | None = Field(default=None, description=AVAILABLE_AT)
+
+
+class PaperReference(OutputModel):
+    id: str
+    reference: str | None = None
+    title: str
+
+
+class PaperLineageResult(QueryResult):
+    paper: PaperReference
+    predecessors: list[PaperReference]
+    successors: list[PaperReference]
+    coverage: Literal["explicit_catalog_links_only"] = "explicit_catalog_links_only"
+    coverage_note: str = (
+        "Only explicit catalog relationships are returned; an empty list does not "
+        "prove that no predecessor or successor exists."
+    )
+
+
+class AreaReference(OutputModel):
+    id: str
+    name: str
+
+
+class BenchmarkSummary(OutputModel):
+    id: str
+    name: str
+    slug: str | None = None
+    full_name: str | None = None
+    description: str | None = None
+    split: str | None = None
+    hf_url: str | None = None
+    paper_count: int
+
+
+class TaskDetail(OutputModel):
+    id: str
+    name: str
+    slug: str
+    description: str | None = None
+    paper_count: int
+    area: AreaReference | None = None
+    parents: list[CatalogReference]
+    children: list[CatalogReference]
+    benchmarks: list[BenchmarkSummary]
+
+
+class TaskResult(QueryResult):
+    task: TaskDetail
+
+
+class MethodDetail(OutputModel):
+    id: str
+    name: str
+    slug: str
+    full_name: str | None = None
+    description: str | None = None
+    introduced_year: int | None = None
+    source_paper_id: str | None = None
+    source_url: str | None = None
+    source_title: str | None = None
+    paper_count: int
+
+
+class MethodResult(QueryResult):
+    method: MethodDetail
+
+
+class BenchmarkPage(QueryResult):
+    items: list[BenchmarkSummary]
+    next_page: int | None = None
+
+
+class EvaluationRankScope(OutputModel):
+    task_id: str | None = None
+    task_name: str | None = None
+    task_slug: str | None = None
+    rank: int | None = None
+
+
+class Evaluation(OutputModel):
+    id: str
+    model_name: str
+    harness: str | None = None
+    metrics: dict[str, float | int | str | None]
+    best_metric: str | None = None
+    best_rank: int | None = None
+    task: str | None = None
+    paper_id: str | None = None
+    paper_title: str | None = None
+    paper_arxiv_id: str | None = None
+    paper_published: str | None = None
+    rank_scopes: list[EvaluationRankScope] = Field(default_factory=list)
+    is_open: bool | None = Field(
+        description=(
+            "Catalog openness flag for the evaluated implementation: true=open, "
+            "false=closed, null=not recorded."
+        )
+    )
+    num_parameters: int | None = None
+    split: str | None = None
+    shots: int | None = None
+    evaluation_protocol: str | None = None
+    source_url: str | None = None
+    code_url: str | None = None
+    hf_model_url: str | None = None
+    updated_at: str | None = None
+    uses_additional_data: bool | None = None
+
+
+class BenchmarkResult(QueryResult):
+    benchmark: BenchmarkSummary
+    evaluation_count: int
+    matched_count: int | None = None
+    evaluations: list[Evaluation]
+    metric_directions: dict[str, Literal["higher", "lower", "unknown"]]
+    page: int
+    next_page: int | None = None
+    metric_note: str | None = Field(
+        default=None,
+        description="Set when a requested metric is not on this leaderboard; the rows are then unfiltered and the note lists the available metrics.",
+    )
+    ranking_note: str = (
+        "Ranks are scoped by task and are not necessarily comparable across "
+        "rank_scopes."
+    )
+
+
+class EvaluationPage(QueryResult):
+    paper: str
+    evaluation_count: int
+    page: int
+    next_page: int | None = None
+    evaluations: list[Evaluation]
+
+
+def _text(value: Any) -> str | None:
+    return str(value) if value not in (None, "") else None
+
+
+def _int(value: Any) -> int | None:
+    if isinstance(value, bool) or value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _urls(values: Any) -> list[str]:
+    urls = []
+    for value in values or []:
+        url = value.get("url") if isinstance(value, dict) else value
+        if url:
+            urls.append(str(url))
+    return urls
+
+
+def paper_summary(item: dict[str, Any]) -> PaperSummary:
+    return PaperSummary(
+        id=str(item.get("id") or ""),
+        arxiv_id=_text(item.get("arxiv_id")),
+        title=str(item.get("title") or "Untitled paper"),
+        authors=[str(author) for author in item.get("authors") or []],
+        published=_text(item.get("published") or item.get("date_published")),
+        citation_count=_int(item.get("citation_count")),
+        url=_text(item.get("url_abs") or item.get("source_url")),
+        has_official_implementation=item.get("has_official_implementation") is True,
+        code_repository_count=int(item.get("code_repository_count") or 0),
+    )
+
+
+def catalog_reference(item: dict[str, Any]) -> CatalogReference:
+    return CatalogReference(
+        id=str(item.get("id") or ""),
+        name=str(item.get("name") or item.get("slug") or "Unknown"),
+        slug=_text(item.get("slug")),
+    )
+
+
+def paper_detail(
+    item: dict[str, Any], *, include_resources: bool = False, repo_limit: int = 5
+) -> PaperDetail:
+    repositories = []
+    for repository in item.get("repositories") or []:
+        if isinstance(repository, dict) and repository.get("url"):
+            value = RepositoryReference(
+                url=str(repository["url"]),
+                is_official=repository.get("is_official") is True,
+            )
+            if include_resources or value.is_official:
+                repositories.append(value)
+    repositories.sort(key=lambda repository: not repository.is_official)
+    repositories = repositories[:repo_limit]
+    return PaperDetail(
+        id=str(item.get("id") or ""),
+        arxiv_id=_text(item.get("arxiv_id")),
+        title=str(item.get("title") or "Untitled paper"),
+        abstract=_text(item.get("abstract")),
+        authors=[str(author) for author in item.get("authors") or []],
+        published=_text(item.get("published")),
+        citation_count=_int(item.get("citation_count")),
+        url=_text(item.get("url_abs") or item.get("source_url")),
+        pdf_url=_text(item.get("url_pdf")),
+        code_repository_count=int(item.get("code_repository_count") or 0),
+        tasks=[
+            catalog_reference(task)
+            for task in item.get("tasks") or []
+            if isinstance(task, dict)
+        ],
+        methods=[
+            catalog_reference(method)
+            for method in item.get("methods") or []
+            if isinstance(method, dict)
+        ],
+        repositories=repositories,
+        project_pages=_urls(item.get("project_pages"))[:repo_limit]
+        if include_resources
+        else [],
+        hf_models=_urls(item.get("hf_models"))[:repo_limit]
+        if include_resources
+        else [],
+        hf_datasets=_urls(item.get("hf_datasets"))[:repo_limit]
+        if include_resources
+        else [],
+        hf_spaces=_urls(item.get("hf_spaces"))[:repo_limit]
+        if include_resources
+        else [],
+        x_threads=[
+            XThreadReference(
+                url=str(thread["url"]),
+                author=str(thread.get("author_name") or ""),
+                handle=str(thread.get("author_handle") or ""),
+            )
+            for thread in item.get("x_threads") or []
+            if isinstance(thread, dict) and thread.get("url")
+        ][:repo_limit]
+        if include_resources
+        else [],
+    )
+
+
+def _metrics(item: dict[str, Any]) -> dict[str, float | int | str | None]:
+    metrics = item.get("metrics")
+    if not isinstance(metrics, dict):
+        return {}
+    return {str(key): value for key, value in metrics.items()}
+
+
+def paper_evaluation(item: dict[str, Any]) -> PaperEvaluation:
+    return PaperEvaluation(
+        id=str(item.get("id") or ""),
+        benchmark=_text(item.get("dataset_name")),
+        task=_text(item.get("task_name")),
+        model_name=str(item.get("model_name") or "Unknown model"),
+        harness=_text(item.get("harness")),
+        metrics=_metrics(item),
+        best_metric=_text(item.get("best_metric")),
+        best_rank=_int(item.get("best_rank")),
+        is_open=item.get("is_open") is not False,
+        num_parameters=_int(item.get("num_parameters")),
+        source_url=_text(item.get("result_url") or item.get("source_url")),
+    )
+
+
+def paper_reference(item: dict[str, Any]) -> PaperReference:
+    reference = item.get("reference") or item.get("arxiv_id")
+    return PaperReference(
+        id=str(item.get("id") or ""),
+        reference=str(reference) if reference else None,
+        title=str(item.get("title") or item.get("reference") or "Untitled paper"),
+    )
+
+
+def benchmark_summary(item: dict[str, Any]) -> BenchmarkSummary:
+    count = (
+        item.get("paper_count")
+        if item.get("paper_count") is not None
+        else item.get("all_time_paper_count", item.get("evaluation_count"))
+    )
+    return BenchmarkSummary(
+        id=str(item.get("id") or ""),
+        name=str(item.get("name") or item.get("slug") or "Unknown benchmark"),
+        slug=_text(item.get("slug")),
+        full_name=_text(item.get("full_name")),
+        description=_text(item.get("description")),
+        split=_text(item.get("split_name") or item.get("split")),
+        hf_url=_text(item.get("hf_url")),
+        paper_count=_int(count) or 0,
+    )
+
+
+def evaluation(item: dict[str, Any]) -> Evaluation:
+    return Evaluation(
+        id=str(item.get("id") or ""),
+        model_name=str(item.get("model_name") or "Unknown model"),
+        harness=_text(item.get("harness")),
+        metrics={name: _metric_value(value) for name, value in _metrics(item).items()},
+        best_metric=_text(item.get("best_metric")),
+        best_rank=_int(item.get("best_rank")),
+        task=_text(item.get("task_name")),
+        paper_id=_text(item.get("paper_id")),
+        paper_title=_text(item.get("paper_title")),
+        paper_arxiv_id=_text(item.get("paper_arxiv_id")),
+        paper_published=_text(item.get("paper_published_date")),
+        rank_scopes=_rank_scopes(item),
+        is_open=(
+            item.get("is_open") if isinstance(item.get("is_open"), bool) else None
+        ),
+        num_parameters=_int(item.get("num_parameters")),
+        split=_text(
+            item.get("split") or item.get("split_name") or item.get("evaluated_on")
+        ),
+        shots=_shot_count(item.get("methodology")),
+        evaluation_protocol=_text(item.get("methodology")),
+        source_url=_absolute_url(
+            item.get("result_url")
+            or item.get("source_url")
+            or item.get("external_source_url")
+        ),
+        code_url=_absolute_url(item.get("code_url")),
+        hf_model_url=_absolute_url(item.get("hf_model_url")),
+        updated_at=_text(item.get("updated_at")),
+        uses_additional_data=(
+            item.get("uses_additional_data")
+            if isinstance(item.get("uses_additional_data"), bool)
+            else None
+        ),
+    )
+
+
+def _rank_scopes(item: dict[str, Any]) -> list[EvaluationRankScope]:
+    existing = item.get("rank_scopes")
+    if isinstance(existing, list):
+        return [
+            EvaluationRankScope.model_validate(scope)
+            for scope in existing
+            if isinstance(scope, dict)
+        ]
+    if not any(
+        item.get(field) is not None for field in ("task_id", "task_name", "best_rank")
+    ):
+        return []
+    return [
+        EvaluationRankScope(
+            task_id=_text(item.get("task_id")),
+            task_name=_text(item.get("task_name")),
+            task_slug=_text(item.get("task_slug")),
+            rank=_int(item.get("best_rank")),
+        )
+    ]
+
+
+def _shot_count(methodology: object) -> int | None:
+    match = re.search(r"\b(\d+)\s*[- ]?shot\b", str(methodology), re.IGNORECASE)
+    return int(match.group(1)) if match else None
+
+
+def _metric_value(value: Any) -> float | int | str | None:
+    if value is None or isinstance(value, (int, float)) and not isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return value
+    return str(value)
+
+
+def metric_directions(
+    evaluations: list[Evaluation],
+) -> dict[str, Literal["higher", "lower", "unknown"]]:
+    lower = {
+        "error",
+        "loss",
+        "perplexity",
+        "latency",
+        "runtime",
+        "wer",
+        "cer",
+        "eer",
+        "fid",
+        "mae",
+        "rmse",
+    }
+    higher = {
+        "accuracy",
+        "precision",
+        "recall",
+        "f1",
+        "bleu",
+        "rouge",
+        "map",
+        "auc",
+        "score",
+        "em",
+    }
+    result: dict[str, Literal["higher", "lower", "unknown"]] = {}
+    for name in sorted({key for row in evaluations for key in row.metrics}):
+        words = set(re.sub(r"[^a-z0-9]+", " ", name.casefold()).split())
+        if words & lower:
+            result[name] = "lower"
+        elif words & higher:
+            result[name] = "higher"
+        else:
+            result[name] = "unknown"
+    return result
+
+
+def public_paper_detail(item: dict[str, Any], *, repo_limit: int = 5) -> PaperDetail:
+    """Project public metadata for a paper outside the catalog.
+
+    Linked repositories come from Hugging Face Papers or the abstract, not
+    catalog curation, so none is marked official.
+    """
+    repositories = [
+        RepositoryReference(url=url, is_official=False)
+        for url in _urls(item.get("repositories"))
+    ][:repo_limit]
+    return PaperDetail(
+        id=str(item.get("id") or ""),
+        arxiv_id=_text(item.get("arxiv_id")),
+        title=str(item.get("title") or "Untitled paper"),
+        abstract=_text(item.get("abstract")),
+        authors=[str(author) for author in item.get("authors") or []],
+        published=_text(item.get("published")),
+        url=_text(item.get("url")),
+        pdf_url=_text(item.get("pdf_url")),
+        code_repository_count=len(repositories),
+        tasks=[],
+        methods=[],
+        repositories=repositories,
+        project_pages=_urls(item.get("project_pages"))[:repo_limit],
+    )
+
+
+def available_at(item: dict[str, Any]) -> list[PaperLink]:
+    return [
+        PaperLink(label=str(link["label"]), url=str(link["url"]), kind=_text(link.get("kind")))
+        for link in item.get("available_at") or []
+        if isinstance(link, dict) and link.get("label") and link.get("url")
+    ]

mcp_server/src/pwc_mcp/server.py

@@ -0,0 +1,1256 @@
+"""MCP tools that mirror every read-only ``pwc`` research command.
+
+Each tool maps one CLI command and exposes each of its research flags as a
+typed parameter, then runs the CLI handler in-process through the catalog.
+``TOOL_COMMANDS``, ``PARAMETER_NAMES``, ``ENTITY_PARAMETERS`` and
+``MCP_ONLY_PARAMETERS`` are the parity contract that ``tests/test_parity.py``
+checks against the CLI parser.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from collections.abc import Mapping
+from datetime import date
+from functools import cache
+from typing import Annotated, Any, Literal, Protocol, TypeVar
+
+from mcp.server.caching import CacheHint
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
+from pwc_cli import queries
+from pwc_cli.cli import UsageError
+from pwc_cli.transport import HTTPStatusError, ResponseError, TransportError
+from pydantic import BaseModel, Field
+
+from pwc_mcp import __version__
+from pwc_mcp.catalog import (
+    PaperMarkdownChunk,
+    PaperVersionMismatchError,
+    PublicPaperMiss,
+    normalize_title,
+)
+from pwc_mcp.cursors import (
+    CURSOR_LIFETIME_SECONDS,
+    MAX_CHUNK_BYTES,
+    CursorCodec,
+    CursorReferenceMismatch,
+    CursorState,
+)
+from pwc_mcp.models import (
+    AreaReference,
+    BenchmarkPage,
+    BenchmarkResult,
+    EvaluationPage,
+    MethodDetail,
+    MethodResult,
+    PaperInfoResult,
+    PaperLineageResult,
+    PaperPage,
+    PaperReadResult,
+    QueryResult,
+    TaskDetail,
+    TaskResult,
+    available_at,
+    benchmark_summary,
+    catalog_reference,
+    evaluation,
+    metric_directions,
+    paper_detail,
+    paper_evaluation,
+    paper_reference,
+    paper_summary,
+    public_paper_detail,
+)
+
+logger = logging.getLogger(__name__)
+READ_ONLY = ToolAnnotations(
+    read_only_hint=True,
+    destructive_hint=False,
+    idempotent_hint=True,
+    open_world_hint=True,
+)
+# Hosted ceiling on rows per response (SPEC.md); the CLI allows up to 100.
+MAX_ROWS = 25
+# Matches `pwc search --mode`; app.py counts omitted modes with this value.
+DEFAULT_SEARCH_MODE = "hybrid"
+# CLI lookup failures the caller can act on (an unknown or ambiguous name, an
+# unconfirmed filter). Transport, HTTP, and response-shape failures stay generic.
+CLIENT_FACING_ERRORS = (
+    "Task not found",
+    "Method not found",
+    "Benchmark not found",
+    "Conference not found",
+    "Organization not found",
+    "Framework not found",
+    "Area not found",
+    "Paper title not found",
+    "Paper title is ambiguous",
+    "Paper not found",
+    "Paper URL not supported",
+    "Paper reference cannot be empty",
+    "Too many results to resolve paper title",
+    "Papers API did not confirm",
+)
+GENERIC_ERROR = "the Papers With Code catalog request failed"
+# Upstream validation failures the caller can correct; the detail is the
+# public API's own message, bounded and stripped of control characters.
+INVALID_ARGUMENT_STATUSES = frozenset({400, 422})
+MAX_UPSTREAM_DETAIL_CHARS = 200
+# Lookup failures meaning the paper itself is absent from the catalog; the
+# paper tools then fall back to the public-metadata API (Hugging Face Papers,
+# arXiv, or Crossref records with the places the paper is available).
+MISSING_PAPER_ERRORS = (
+    "Paper not found",
+    "Paper title not found",
+    "Paper URL not supported",
+)
+# Placeholder cursors agents send instead of a next_cursor token ("next" with
+# nothing saved); they mean "keep reading", which starts at the beginning.
+PLACEHOLDER_CURSORS = frozenset(
+    {"next", "start", "begin", "beginning", "first", "0", "1", "none", "null"}
+)
+NOT_IN_CATALOG = "not indexed on Papers With Code"
+METADATA_SOURCES = {
+    "huggingface": "Hugging Face Papers",
+    "arxiv": "arXiv",
+    "crossref": "Crossref",
+}
+
+
+class PaperNotInCatalog(ToolError):
+    """A paper tool's reference does not name a catalog paper."""
+
+
+def _is_missing_paper(error: Exception) -> bool:
+    if isinstance(error, HTTPStatusError):
+        return error.status == 404
+    return (
+        isinstance(error, ResponseError)
+        and not isinstance(error, TransportError)
+        and str(error).startswith(MISSING_PAPER_ERRORS)
+    )
+
+
+# Why a catalog miss has no public record, worded by what was actually tried.
+PUBLIC_MISSES: dict[str, str] = {
+    "identifier": "no public Hugging Face Papers, arXiv, or Crossref record matched it",
+    "title": (
+        "no arXiv or Crossref paper has exactly this title; check the title or "
+        "retry with the paper's arXiv ID, DOI, or URL"
+    ),
+    "unsupported": (
+        "it was not looked up publicly, because that needs an arXiv ID, DOI, "
+        "arXiv or Hugging Face URL, or the full title"
+    ),
+    "unavailable": (
+        "the public Hugging Face Papers, arXiv, and Crossref lookup is "
+        "unavailable right now, so whether a public record exists is unknown"
+    ),
+}
+
+
+def _public_note(record: dict[str, Any]) -> str:
+    links = "; ".join(f"{link.label}: {link.url}" for link in available_at(record))
+    requested = record.get("requested_title")
+    renamed = (
+        f'No paper is titled exactly "{requested}"; this is the paper with the '
+        f'same name, titled "{record.get("title")}". '
+        if requested and normalize_title(requested) != normalize_title(record.get("title"))
+        else ""
+    )
+    return (
+        f"{renamed}This paper is {NOT_IN_CATALOG}, so there is no Papers With Code page, "
+        "catalog tasks, methods, evaluations, or curated code for it; metadata comes "
+        "from public "
+        f"{METADATA_SOURCES.get(str(record.get('metadata_source')), 'arXiv')} "
+        "records. "
+        + (
+            f"Link to where it is available instead: {links}."
+            if links
+            else "Do not link to a Papers With Code page for it."
+        )
+    )
+
+
+def _public_markdown(record: dict[str, Any]) -> str:
+    lines = [
+        f"# {record.get('title') or 'Untitled paper'}",
+        "",
+        f"> {_public_note(record)} Full text is unavailable here.",
+        "",
+    ]
+    if record.get("authors"):
+        lines.append(f"**Authors:** {', '.join(record['authors'])}")
+    if record.get("published"):
+        lines.append(f"**Published:** {record['published']}")
+    links = available_at(record)
+    if links:
+        lines.extend(["", "## Available at", ""])
+        lines.extend(f"- [{link.label}]({link.url})" for link in links)
+    if record.get("abstract"):
+        lines.extend(["", "## Abstract", "", str(record["abstract"])])
+    return "\n".join(lines) + "\n"
+
+
+def _upstream_detail(error: HTTPStatusError) -> str:
+    detail = "".join(
+        ch if ch.isprintable() else " " for ch in str(error.detail or "")
+    ).strip()
+    return detail[:MAX_UPSTREAM_DETAIL_CHARS] or "the catalog rejected the request"
+
+
+def catalog_error_message(error: Exception) -> str:
+    """Return the CLI's own lookup message when it is actionable, else a generic one."""
+    if isinstance(error, HTTPStatusError):
+        if error.status == 404:
+            return "not_found: the requested catalog record does not exist"
+        if error.status in INVALID_ARGUMENT_STATUSES:
+            return f"invalid_argument: {_upstream_detail(error)}"
+        if error.status == 429:
+            return "rate_limited: the Papers With Code catalog is rate limiting; retry later"
+    if isinstance(error, TransportError):
+        message = str(error).casefold()
+        if "timeout" in message or "timed out" in message:
+            return "upstream_timeout: the Papers With Code catalog timed out"
+    if isinstance(error, ResponseError) and not isinstance(error, TransportError):
+        message = str(error)
+        if message.startswith(CLIENT_FACING_ERRORS):
+            code = "ambiguous" if "ambiguous" in message.casefold() else "not_found"
+            return f"{code}: {message}"
+    # Only the exception class is logged: never the reference, query, or body.
+    logger.warning("pwc-mcp generic catalog error type=%s", type(error).__name__)
+    return f"upstream_error: {GENERIC_ERROR}"
+
+
+# One read-only CLI command per tool.
+TOOL_COMMANDS: dict[str, tuple[str, ...]] = {
+    "search_papers": ("search",),
+    "get_paper_info": ("paper", "info"),
+    "get_paper_evaluations": ("paper", "evaluations"),
+    "read_paper": ("paper", "read"),
+    "list_papers": ("paper", "list"),
+    "list_recent_papers": ("paper", "recent"),
+    "list_trending_papers": ("paper", "trending"),
+    "get_related_papers": ("paper", "related"),
+    "get_paper_lineage": ("paper", "lineage", "list"),
+    "get_task": ("task",),
+    "list_tasks": ("task", "list"),
+    "get_method": ("method",),
+    "list_methods": ("method", "list"),
+    "get_conference": ("conference",),
+    "list_conferences": ("conference", "list"),
+    "get_organization": ("organization",),
+    "list_organizations": ("organization", "list"),
+    "get_framework": ("framework",),
+    "list_frameworks": ("framework", "list"),
+    "get_benchmark": ("benchmark",),
+    "list_benchmarks": ("benchmark", "list"),
+}
+# CLI destinations that keep their established MCP parameter name.
+PARAMETER_NAMES: dict[str, str] = {
+    "start_date": "published_after",
+    "end_date": "published_before",
+    "page_size": "limit",
+    "author": "authors",
+    "order_dir": "order_direction",
+    "min_eval_count": "minimum_evaluations",
+    "include_evals": "include_evaluations",
+}
+# ``--name`` selects the tool's entity and is exposed under the entity's name.
+ENTITY_PARAMETERS: dict[str, str] = {
+    "get_task": "task",
+    "get_method": "method",
+    "get_conference": "conference",
+    "get_organization": "organization",
+    "get_framework": "framework",
+    "get_benchmark": "benchmark",
+}
+# Parameters with no CLI flag; ``read_paper`` continues with a signed cursor.
+MCP_ONLY_PARAMETERS: dict[str, frozenset[str]] = {
+    "read_paper": frozenset({"cursor"}),
+    "get_paper_info": frozenset({"repo_limit"}),
+    "get_task": frozenset({"benchmark_limit"}),
+}
+_CLI_DESTINATIONS = {mcp: cli for cli, mcp in PARAMETER_NAMES.items()}
+
+
+@cache
+def _cli_destinations(tool: str) -> frozenset[str]:
+    return frozenset(queries.query_options(TOOL_COMMANDS[tool]))
+
+
+def cli_options(tool: str, **parameters: Any) -> dict[str, Any]:
+    """Translate MCP parameters into the CLI destinations of ``tool``.
+
+    A parameter keeps its name when the command has that flag (``--limit``),
+    and otherwise follows ``PARAMETER_NAMES`` (``limit`` -> ``--page-size``).
+    """
+    entity = ENTITY_PARAMETERS.get(tool)
+    destinations = _cli_destinations(tool)
+    options: dict[str, Any] = {}
+    for name, value in parameters.items():
+        if name in MCP_ONLY_PARAMETERS.get(tool, frozenset()):
+            continue
+        if name == entity:
+            destination = "name"
+        elif name in destinations:
+            destination = name
+        else:
+            destination = _CLI_DESTINATIONS.get(name, name)
+        options[destination] = value
+    return options
+
+
+Page = Annotated[int, Field(ge=1, le=100, description="Result page, starting at 1.")]
+Limit = Annotated[
+    int, Field(ge=1, le=MAX_ROWS, description="Rows per response, at most 25.")
+]
+Reference = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=500,
+        description="arXiv ID, numeric PwC ID, arXiv/Hugging Face/PwC URL, or exact title.",
+    ),
+]
+Query = Annotated[str, Field(min_length=1, max_length=500)]
+Entity = Annotated[str, Field(min_length=1, max_length=500)]
+IsoDate = Annotated[
+    str, Field(max_length=10, description="Inclusive publication date, YYYY-MM-DD.")
+]
+AuthorList = Annotated[
+    list[str],
+    Field(
+        max_length=10,
+        description="Exact author names, numeric IDs, or @HF_USERNAME; every author must match.",
+    ),
+]
+ResourceLimit = Annotated[int, Field(ge=1, le=10)]
+Output = TypeVar("Output", bound=BaseModel)
+
+
+def _tool_result(value: Output, markdown: str) -> CallToolResult:
+    return CallToolResult(
+        content=[TextContent(type="text", text=markdown)],
+        structured_content=value.model_dump(mode="json"),
+    )
+
+
+def _structured_model(result: Any, model: type[Output]) -> Output:
+    if isinstance(result, CallToolResult):
+        return model.model_validate(result.structured_content)
+    return result
+
+
+Area = Annotated[str, Field(description="Case-insensitive exact area name or area ID.")]
+Direction = Literal["asc", "desc"]
+ParameterSize = Annotated[
+    str,
+    Field(
+        max_length=32,
+        description="Inclusive model-size limit such as 500M, 1.5B, 3B, or a raw integer.",
+    ),
+]
+MetricNames = Annotated[
+    list[str],
+    Field(
+        min_length=1, description="Metric names that every returned row must report."
+    ),
+]
+MetricBounds = Annotated[
+    dict[str, float], Field(description="Metric name to numeric threshold.")
+]
+SortMetric = Annotated[
+    str,
+    Field(
+        max_length=200,
+        description="METRIC or METRIC:asc|desc; default direction is desc.",
+    ),
+]
+ParetoObjectives = Annotated[
+    list[str],
+    Field(
+        min_length=2,
+        description="Two or more METRIC:higher or METRIC:lower objectives; keeps the Pareto frontier.",
+    ),
+]
+
+
+def _validate_date_range(start: str | None, end: str | None) -> None:
+    try:
+        start_date = date.fromisoformat(start) if start else None
+        end_date = date.fromisoformat(end) if end else None
+    except ValueError as error:
+        raise ToolError("publication dates must use YYYY-MM-DD") from error
+    if start_date and end_date and start_date > end_date:
+        raise ToolError("published_after must be on or before published_before")
+
+
+def _dicts(values: Any) -> list[dict[str, Any]]:
+    return [value for value in values or [] if isinstance(value, dict)]
+
+
+def _next_page(data: Any) -> int | None:
+    value = data.get("next_page") if isinstance(data, dict) else None
+    return int(value) if value is not None else None
+
+
+def _paper_page(data: Any) -> PaperPage:
+    """Project a paper listing; recent/trending endpoints return a bare list."""
+    if isinstance(data, list):
+        rows: Any = data
+    elif isinstance(data, dict):
+        rows = data.get("results")
+    else:
+        raise TypeError("paper listing did not contain a result document")
+    return PaperPage(
+        items=[paper_summary(item) for item in _dicts(rows)],
+        next_page=_next_page(data),
+        data=data,
+    )
+
+
+def _grouped_benchmarks(areas: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        benchmark
+        for area in areas
+        for task in _dicts(area.get("tasks"))
+        for benchmark in _dicts(task.get("benchmarks"))
+    ]
+
+
+class Catalog(Protocol):
+    def resolve_paper(self, paper: str) -> str: ...
+
+    def read_paper_chunk(
+        self,
+        paper: str,
+        *,
+        offset: int = 0,
+        content_version: str | None = None,
+        limit: int = MAX_CHUNK_BYTES,
+        resolved: bool = False,
+    ) -> PaperMarkdownChunk: ...
+
+    def query(self, command: tuple[str, ...], options: Mapping[str, Any]) -> Any: ...
+
+    def public_paper(self, reference: str) -> dict[str, Any] | PublicPaperMiss: ...
+
+
+def build_server(
+    catalog: Catalog,
+    *,
+    read_chunk_bytes: int = MAX_CHUNK_BYTES,
+    cursor_codec: CursorCodec | None = None,
+) -> MCPServer:
+    codec = cursor_codec or CursorCodec(
+        os.environ.get("PWC_MCP_CURSOR_KEY_CURRENT", ""),
+        previous_secret=os.environ.get("PWC_MCP_CURSOR_KEY_PREVIOUS") or None,
+    )
+    server = MCPServer(
+        "pwc",
+        title="Papers With Code",
+        description=(
+            "Read-only access to papers, tasks, methods, conferences, organizations, "
+            "frameworks, and benchmarks; every pwc CLI research command and flag."
+        ),
+        instructions=(
+            "Use search_papers for relevance and list tools for deterministic filters. "
+            "Pass slugs or numeric IDs returned by list tools to exact lookup tools. "
+            "Dates use YYYY-MM-DD. Structured data is in structuredContent; text is a "
+            "short Markdown summary. Official implementation means catalog-designated "
+            "official code, not an independent audit. Evaluation is_open describes the "
+            "cataloged implementation and may be null when unknown."
+        ),
+        version=__version__,
+        website_url="https://paperswithcode.co",
+        cache_hints={
+            "server/discover": CacheHint(ttl_ms=3_600_000, scope="public"),
+            "tools/list": CacheHint(ttl_ms=3_600_000, scope="public"),
+            "resources/templates/list": CacheHint(ttl_ms=3_600_000, scope="public"),
+            "resources/read": CacheHint(ttl_ms=300_000, scope="public"),
+        },
+    )
+
+    def run(tool: str, **parameters: Any) -> Any:
+        """Run the tool's CLI command; surface usage errors, hide upstream detail."""
+        try:
+            return catalog.query(TOOL_COMMANDS[tool], cli_options(tool, **parameters))
+        except UsageError as error:
+            raise ToolError(str(error)) from error
+        except (ResponseError, TransportError) as error:
+            if "paper" in parameters and _is_missing_paper(error):
+                raise PaperNotInCatalog(catalog_error_message(error)) from error
+            raise ToolError(catalog_error_message(error)) from error
+
+    def public_paper(reference: str, missing: ToolError) -> dict[str, Any]:
+        """Public metadata for a catalog miss, or the original error."""
+        record = catalog.public_paper(reference)
+        if isinstance(record, PublicPaperMiss):
+            raise ToolError(
+                f"{missing}; it is {NOT_IN_CATALOG} and {PUBLIC_MISSES[record.reason]}"
+            ) from missing
+        return record
+
+    def catalog_alternatives(reference: str, record: dict[str, Any]) -> list[str]:
+        """Catalog IDs the public-metadata API resolved a missed reference to.
+
+        An arXiv URL or versioned ID the catalog lookup missed may name a
+        catalog paper. The arXiv ID comes first: Markdown reads key arXiv papers
+        by it, not by the numeric catalog ID.
+        """
+        if record.get("in_catalog") is not True:
+            return []
+        candidates = (record.get("arxiv_id"), record.get("catalog_id"))
+        return [
+            str(value).strip()
+            for value in candidates
+            if value and str(value).strip() != reference.strip()
+        ]
+
+    def catalog_retry(
+        tool: str,
+        reference: str,
+        record: dict[str, Any],
+        missing: ToolError,
+        **parameters: Any,
+    ) -> Any:
+        """Retry the catalog with the catalog ID the public-metadata API found.
+
+        Returns None for a paper outside the catalog; a cataloged paper that
+        still cannot be read keeps the original error rather than being
+        presented as outside the catalog.
+        """
+        for alternative in catalog_alternatives(reference, record):
+            try:
+                return run(tool, paper=str(alternative), **parameters)
+            except ToolError:
+                continue
+        if record.get("in_catalog") is True:
+            raise missing
+        return None
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def search_papers(
+        query: Query,
+        mode: Literal["hybrid", "keyword", "semantic"] = DEFAULT_SEARCH_MODE,
+        page: Page = 1,
+        limit: Limit = 10,
+        published_after: IsoDate | None = None,
+        published_before: IsoDate | None = None,
+        has_official_implementation: bool = False,
+    ) -> PaperPage:
+        """Search papers by title, topic, author, or arXiv ID (`pwc search`). Broad discovery only: for best, top, or state-of-the-art model questions start with get_task, list_benchmarks, and get_benchmark, which return leaderboard evidence that search cannot. Mode defaults to hybrid like `pwc search`; use keyword for exact terminology or to stay under the semantic search rate limit."""
+        _validate_date_range(published_after, published_before)
+        result = _paper_page(
+            run(
+                "search_papers",
+                query=query,
+                mode=mode,
+                page=page,
+                limit=limit,
+                published_after=published_after,
+                published_before=published_before,
+                has_official_implementation=has_official_implementation,
+            )
+        )
+        return _tool_result(
+            result,
+            f"Found {len(result.items)} papers."
+            + (f" Next page: {result.next_page}." if result.next_page else ""),
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_paper_info(
+        paper: Reference,
+        include_resources: bool = False,
+        repo_limit: ResourceLimit = 5,
+        include_evaluations: bool = False,
+    ) -> PaperInfoResult:
+        """Get compact paper metadata and official-first code. Set include_resources for additional repositories, project pages, Hugging Face artifacts, and author X threads introducing the paper, repo_limit to cap each list, and include_evaluations only for bounded legacy compatibility (`pwc paper info`). A paper not indexed on Papers With Code returns public Hugging Face Papers, arXiv, or Crossref metadata with in_catalog=false, a note, and available_at links to cite instead of a Papers With Code page."""
+        options = {
+            # Fetch once so the compact default can retain official code while
+            # omitting hundreds of community repositories from the response.
+            "include_resources": True,
+            "include_evaluations": include_evaluations,
+        }
+        try:
+            data = run("get_paper_info", paper=paper, **options)
+        except PaperNotInCatalog as missing:
+            record = public_paper(paper, missing)
+            data = catalog_retry("get_paper_info", paper, record, missing, **options)
+            if data is None:
+                detail = public_paper_detail(record, repo_limit=repo_limit)
+                note = _public_note(record)
+                result = PaperInfoResult(
+                    paper=detail,
+                    in_catalog=False,
+                    note=note,
+                    available_at=available_at(record),
+                    data=None,
+                )
+                return _tool_result(result, f"## {detail.title}\n\n{note}")
+        if not isinstance(data, dict):
+            raise TypeError("paper response did not contain a paper")
+        evaluations = data.get("evaluations")
+        result = PaperInfoResult(
+            paper=paper_detail(
+                data, include_resources=include_resources, repo_limit=repo_limit
+            ),
+            evaluation_count=(
+                int(evaluations.get("count") or 0)
+                if isinstance(evaluations, dict)
+                else None
+            ),
+            evaluations=(
+                [paper_evaluation(item) for item in _dicts(evaluations.get("results"))]
+                if isinstance(evaluations, dict)
+                else None
+            ),
+            data=None,
+        )
+        return _tool_result(
+            result,
+            f"## {result.paper.title}\n\n{result.paper.code_repository_count} code repositories; returned {len(result.paper.repositories)}.",
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_paper_evaluations(
+        paper: Reference, page: Page = 1, limit: Limit = 20
+    ) -> EvaluationPage:
+        """Get one page of benchmark evaluations for a paper, including protocol, source, openness, and task-scoped ranks (`pwc paper evaluations`)."""
+        data = run("get_paper_evaluations", paper=paper, page=page, limit=limit)
+        rows = _dicts(data.get("results")) if isinstance(data, dict) else []
+        values = [evaluation(row) for row in rows]
+        result = EvaluationPage(
+            paper=paper,
+            evaluation_count=int(data.get("count") or len(values)),
+            page=page,
+            next_page=_next_page(data),
+            evaluations=values,
+            data=None,
+        )
+        return _tool_result(
+            result,
+            f"Found {result.evaluation_count} evaluation rows; returned {len(values)} on page {page}."
+            + (f" Next page: {result.next_page}." if result.next_page else ""),
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def read_paper(paper: Reference, cursor: str | None = None) -> PaperReadResult:
+        """Read stored paper Markdown, continuing oversized documents with a cursor (`pwc paper read`). Pass the next_cursor value from the previous result together with the same paper (any reference to that paper works); omit cursor to start from the beginning. A paper not indexed on Papers With Code returns its public metadata and abstract as Markdown with in_catalog=false and available_at links to cite instead of a Papers With Code page."""
+        if cursor is not None and cursor.strip().casefold() in PLACEHOLDER_CURSORS:
+            # Not a token: nothing was saved to continue from.
+            cursor = None
+        return read(paper.strip(), cursor, follow_public=True)
+
+    def read(
+        reference: str, cursor: str | None, *, follow_public: bool
+    ) -> PaperReadResult:
+        try:
+            state = codec.decode(cursor, reference=reference) if cursor else None
+        except CursorReferenceMismatch as error:
+            # The agent continued with another spelling of the same paper, for
+            # example the numeric catalog ID after starting from the arXiv ID.
+            try:
+                canonical = catalog.resolve_paper(reference)
+            except (ResponseError, TransportError) as inner:
+                raise ToolError(catalog_error_message(inner)) from inner
+            if canonical != error.state.paper:
+                raise ToolError(
+                    "continuation cursor belongs to a different paper; omit cursor "
+                    "to start reading this paper from the beginning"
+                ) from error
+            state = error.state
+        except ValueError as error:
+            raise ToolError(
+                f"{error}; pass the next_cursor value from the previous read_paper "
+                "result, or omit cursor to start from the beginning"
+            ) from error
+        if state is None:
+            try:
+                canonical = catalog.resolve_paper(reference)
+            except (ResponseError, TransportError) as error:
+                if _is_missing_paper(error):
+                    return public_read(reference, error, follow=follow_public)
+                raise ToolError(catalog_error_message(error)) from error
+            offset = 0
+            content_version = None
+            limit = read_chunk_bytes
+            expires_at = int(time.time()) + CURSOR_LIFETIME_SECONDS
+            source = "external" if canonical.isdigit() else "arxiv"
+        else:
+            canonical = state.paper
+            offset = state.offset
+            content_version = state.content_version
+            limit = state.limit
+            expires_at = state.expires_at
+            source = state.source
+        try:
+            chunk = catalog.read_paper_chunk(
+                canonical,
+                offset=offset,
+                content_version=content_version,
+                limit=limit,
+                resolved=True,
+            )
+        except PaperVersionMismatchError as error:
+            raise ToolError(
+                "paper changed; restart reading from the beginning"
+            ) from error
+        except HTTPStatusError as error:
+            if error.status == 404:
+                raise ToolError(
+                    "no_markdown: no stored Markdown is available for this paper"
+                ) from error
+            raise ToolError(catalog_error_message(error)) from error
+        except (ResponseError, TransportError) as error:
+            if state is None and _is_missing_paper(error):
+                return public_read(reference, error, follow=follow_public)
+            raise ToolError(catalog_error_message(error)) from error
+        if chunk.paper != canonical or chunk.source != source:
+            raise ToolError("paper changed; restart reading from the beginning")
+        next_cursor = None
+        if chunk.next_offset is not None:
+            next_cursor = codec.encode(
+                CursorState(
+                    reference=reference,
+                    paper=canonical,
+                    source=source,
+                    content_version=chunk.content_version,
+                    offset=chunk.next_offset,
+                    limit=limit,
+                    expires_at=expires_at,
+                )
+            )
+        return PaperReadResult(
+            paper=reference,
+            markdown=chunk.markdown,
+            truncated=chunk.truncated,
+            next_cursor=next_cursor,
+        )
+
+    def public_read(
+        reference: str, error: Exception, *, follow: bool
+    ) -> PaperReadResult:
+        missing = PaperNotInCatalog(catalog_error_message(error))
+        record = public_paper(reference, missing)
+        # The public-metadata API may resolve the reference to a catalog paper.
+        # The result names that paper's ID, so continuation cursors match it.
+        for alternative in catalog_alternatives(reference, record) if follow else []:
+            try:
+                result = read(alternative, None, follow_public=False)
+            except ToolError:
+                continue
+            if result.in_catalog:
+                return result
+        if record.get("in_catalog") is True:
+            raise missing
+        return PaperReadResult(
+            paper=reference,
+            markdown=_public_markdown(record),
+            truncated=False,
+            next_cursor=None,
+            in_catalog=False,
+            available_at=available_at(record),
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_papers(
+        search: str | None = None,
+        task: str | None = None,
+        method: str | None = None,
+        conference: str | None = None,
+        framework: str | None = None,
+        organization: str | None = None,
+        authors: AuthorList | None = None,
+        published_after: IsoDate | None = None,
+        published_before: IsoDate | None = None,
+        all_versions: bool = False,
+        order_by: Literal["trending", "date_published", "citation_count"] = "trending",
+        order_direction: Direction = "desc",
+        include_resources: bool = False,
+        has_official_implementation: bool = False,
+        page: Page = 1,
+        limit: Limit = 20,
+    ) -> PaperPage:
+        """List and filter papers by exact catalog associations in a deterministic order (`pwc paper list`)."""
+        _validate_date_range(published_after, published_before)
+        return _paper_page(
+            run(
+                "list_papers",
+                search=search,
+                task=task,
+                method=method,
+                conference=conference,
+                framework=framework,
+                organization=organization,
+                authors=authors or None,
+                published_after=published_after,
+                published_before=published_before,
+                all_versions=all_versions,
+                order_by=order_by,
+                order_direction=order_direction,
+                include_resources=include_resources,
+                has_official_implementation=has_official_implementation,
+                page=page,
+                limit=limit,
+            )
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_recent_papers(limit: Limit = 10) -> PaperPage:
+        """List the most recently added papers (`pwc paper recent`)."""
+        return _paper_page(run("list_recent_papers", limit=limit))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_trending_papers(
+        limit: Limit = 20,
+        max_age_days: Annotated[int, Field(ge=1, le=365)] = 180,
+        min_velocity: float | None = None,
+    ) -> PaperPage:
+        """List trending papers by repository velocity (`pwc paper trending`)."""
+        return _paper_page(
+            run(
+                "list_trending_papers",
+                limit=limit,
+                max_age_days=max_age_days,
+                min_velocity=min_velocity,
+            )
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_related_papers(
+        paper: Reference, limit: Annotated[int, Field(ge=1, le=20)] = 4
+    ) -> PaperPage:
+        """Find catalog papers related to one paper (`pwc paper related`). A paper not indexed on Papers With Code falls back to a catalog search for its public title, with a note and available_at links for the paper itself."""
+        try:
+            return _paper_page(run("get_related_papers", paper=paper, limit=limit))
+        except PaperNotInCatalog as missing:
+            record = public_paper(paper, missing)
+            data = catalog_retry(
+                "get_related_papers", paper, record, missing, limit=limit
+            )
+        if data is not None:
+            return _paper_page(data)
+        result = _paper_page(
+            run(
+                "search_papers",
+                query=str(record.get("title") or paper)[:500],
+                mode=DEFAULT_SEARCH_MODE,
+                page=1,
+                limit=limit,
+            )
+        )
+        result.note = (
+            f"{record.get('title') or paper} is {NOT_IN_CATALOG}; these are catalog "
+            "search results for its title, not curated related papers. Link to the "
+            "paper itself through available_at, not a Papers With Code page."
+        )
+        result.available_at = available_at(record)
+        return _tool_result(result, result.note)
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_paper_lineage(paper: Reference) -> PaperLineageResult:
+        """Get explicit predecessor and successor papers (`pwc paper lineage list`)."""
+        data = run("get_paper_lineage", paper=paper)
+        current = data.get("paper") if isinstance(data, dict) else None
+        if not isinstance(current, dict):
+            raise TypeError("lineage response did not contain a paper")
+        return PaperLineageResult(
+            paper=paper_reference(current),
+            predecessors=[
+                paper_reference(item) for item in _dicts(data.get("predecessors"))
+            ],
+            successors=[
+                paper_reference(item) for item in _dicts(data.get("successors"))
+            ],
+            data=data,
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_task(task: Entity, benchmark_limit: ResourceLimit = 10) -> TaskResult:
+        """Get one exact task by name, slug, or ID with its hierarchy, ranked benchmarks, common methods, and trending papers (`pwc task --name`). Start here for any question about the best or state-of-the-art models for a task, then inspect a leaderboard with get_benchmark."""
+        data = run("get_task", task=task)
+        item = data.get("task") if isinstance(data, dict) else None
+        if not isinstance(item, dict):
+            raise TypeError("task response did not contain a task")
+        area_item = data.get("area")
+        result = TaskResult(
+            task=TaskDetail(
+                id=str(item.get("id") or ""),
+                name=str(item.get("name") or "Unknown task"),
+                slug=str(item.get("slug") or item.get("id") or ""),
+                description=(
+                    str(item["description"]) if item.get("description") else None
+                ),
+                paper_count=int(
+                    item.get("paper_count") or data.get("paper_count") or 0
+                ),
+                area=(
+                    AreaReference(
+                        id=str(area_item.get("id") or ""),
+                        name=str(area_item.get("name") or "Unknown area"),
+                    )
+                    if isinstance(area_item, dict)
+                    else None
+                ),
+                parents=[catalog_reference(v) for v in _dicts(data.get("parents"))],
+                children=[catalog_reference(v) for v in _dicts(data.get("children"))],
+                benchmarks=[
+                    benchmark_summary(v) for v in _dicts(data.get("benchmarks"))
+                ][:benchmark_limit],
+            ),
+            data=None,
+        )
+        return _tool_result(
+            result,
+            f"## {result.task.name}\n\n{result.task.paper_count} papers; returned {len(result.task.benchmarks)} benchmarks.",
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_tasks(
+        search: str | None = None,
+        area: Area | None = None,
+        level: int | None = None,
+        visible_only: bool = False,
+        group_by_area: bool = False,
+        order_by: Literal["name", "created_at", "level", "paper_count"] = "name",
+        order_direction: Direction = "asc",
+        page: Page = 1,
+        limit: Limit | None = None,
+    ) -> QueryResult:
+        """List and filter research tasks, or group the visible top-level taxonomy by area (`pwc task list`)."""
+        return QueryResult(
+            data=run(
+                "list_tasks",
+                search=search,
+                area=area,
+                level=level,
+                visible_only=visible_only,
+                group_by_area=group_by_area,
+                order_by=order_by,
+                order_direction=order_direction,
+                page=page,
+                limit=limit if limit is not None or group_by_area else MAX_ROWS,
+            )
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_method(method: Entity) -> MethodResult:
+        """Get one method by name, full name, slug, ID, or curated keyword alias (`pwc method --name`)."""
+        data = run("get_method", method=method)
+        item = data.get("method") if isinstance(data, dict) else None
+        if not isinstance(item, dict):
+            raise TypeError("method response did not contain a method")
+        result = MethodResult(
+            method=MethodDetail(
+                id=str(item.get("id") or ""),
+                name=str(item.get("name") or "Unknown method"),
+                slug=str(item.get("slug") or item.get("id") or ""),
+                full_name=str(item["full_name"]) if item.get("full_name") else None,
+                description=(
+                    str(item["description"]) if item.get("description") else None
+                ),
+                introduced_year=(
+                    int(item["introduced_year"])
+                    if item.get("introduced_year") is not None
+                    else None
+                ),
+                source_paper_id=(
+                    str(item["source_paper_id"])
+                    if item.get("source_paper_id")
+                    else None
+                ),
+                source_url=(
+                    f"https://paperswithcode.co{item['source_url']}"
+                    if str(item.get("source_url") or "").startswith("/")
+                    else str(item["source_url"])
+                    if item.get("source_url")
+                    else None
+                ),
+                source_title=(
+                    str(item["source_title"]) if item.get("source_title") else None
+                ),
+                paper_count=int(item.get("paper_count") or 0),
+            ),
+            data=None,
+        )
+        return _tool_result(
+            result, f"## {result.method.name}\n\n{result.method.paper_count} papers."
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_methods(
+        search: str | None = None,
+        area: Area | None = None,
+        introduced_year: int | None = None,
+        order_by: Literal[
+            "name", "full_name", "introduced_year", "created_at", "paper_count"
+        ] = "name",
+        order_direction: Direction = "asc",
+        page: Page = 1,
+        limit: Limit = MAX_ROWS,
+    ) -> QueryResult:
+        """List and filter research methods (`pwc method list`)."""
+        return QueryResult(
+            data=run(
+                "list_methods",
+                search=search,
+                area=area,
+                introduced_year=introduced_year,
+                order_by=order_by,
+                order_direction=order_direction,
+                page=page,
+                limit=limit,
+            )
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_conference(conference: Entity) -> QueryResult:
+        """Get one exact conference by name, slug, or ID (`pwc conference --name`)."""
+        return QueryResult(data=run("get_conference", conference=conference))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_conferences(year: int | None = None) -> QueryResult:
+        """List conferences with imported papers (`pwc conference list`)."""
+        return QueryResult(data=run("list_conferences", year=year))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_organization(organization: Entity) -> QueryResult:
+        """Get one exact research organization by name, slug, or ID (`pwc organization --name`)."""
+        return QueryResult(data=run("get_organization", organization=organization))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_organizations(featured_only: bool = False) -> QueryResult:
+        """List research organizations (`pwc organization list`)."""
+        return QueryResult(data=run("list_organizations", featured_only=featured_only))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_framework(framework: Entity) -> QueryResult:
+        """Get one exact research framework by name, slug, or ID (`pwc framework --name`)."""
+        return QueryResult(data=run("get_framework", framework=framework))
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_frameworks(
+        domain: str | None = None,
+        category: str | None = None,
+        platform: str | None = None,
+    ) -> QueryResult:
+        """List research frameworks by domain, category, or platform (`pwc framework list`)."""
+        return QueryResult(
+            data=run(
+                "list_frameworks", domain=domain, category=category, platform=platform
+            )
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def get_benchmark(
+        benchmark: Entity,
+        page: Page = 1,
+        limit: Limit = 20,
+        is_open: bool | None = None,
+        max_parameters: ParameterSize | None = None,
+        require_metrics: MetricNames | None = None,
+        minimum_metrics: MetricBounds | None = None,
+        maximum_metrics: MetricBounds | None = None,
+        sort_metric: SortMetric | None = None,
+        pareto: ParetoObjectives | None = None,
+    ) -> BenchmarkResult:
+        """Get one exact benchmark and its leaderboard (`pwc benchmark --name`). Use max_parameters (for example "4B") to keep models at or below a size, sort_metric to rank by a metric, and minimum_metrics, maximum_metrics, require_metrics, or pareto to select rows; matched_count reports how many rows passed before limit. Metric names are matched case-insensitively, through common aliases (AP/mAP, top1/Accuracy, AUROC/AUC, Pass@1/Pass Rate), and by the one leaderboard metric containing the request or an alias of it (Normalized Score for "D4RL Normalized Score", GenEval Score for "Overall"); a metric the leaderboard does not report returns the unfiltered leaderboard with metric_note listing its actual metric names."""
+        options = {
+            "benchmark": benchmark,
+            "page": page,
+            "limit": limit,
+            "is_open": is_open,
+            "max_parameters": max_parameters,
+        }
+        metric_note = None
+        try:
+            data = run(
+                "get_benchmark",
+                **options,
+                require_metrics=require_metrics,
+                minimum_metrics=minimum_metrics,
+                maximum_metrics=maximum_metrics,
+                sort_metric=sort_metric,
+                pareto=pareto,
+            )
+        except ToolError as error:
+            # A metric the leaderboard does not report ("overall", "pass@1")
+            # still deserves the leaderboard, with its real metric names.
+            if not str(error).startswith("unknown metric"):
+                raise
+            data = run("get_benchmark", **options)
+            metric_note = (
+                f"{error}; returned the leaderboard without metric filters or "
+                "metric sorting"
+            )
+        item = data.get("benchmark") if isinstance(data, dict) else None
+        if not isinstance(item, dict):
+            raise TypeError("benchmark response did not contain a benchmark")
+        matched = data.get("matched_count")
+        evaluations = [evaluation(value) for value in _dicts(data.get("results"))]
+        result = BenchmarkResult(
+            benchmark=benchmark_summary(item),
+            evaluation_count=int(data.get("count") or 0),
+            matched_count=int(matched) if matched is not None else None,
+            evaluations=evaluations,
+            metric_directions=metric_directions(evaluations),
+            page=page,
+            next_page=_next_page(data),
+            metric_note=metric_note,
+            data=None,
+        )
+        return _tool_result(
+            result,
+            f"## {result.benchmark.name}\n\n{result.evaluation_count} evaluation rows; returned {len(result.evaluations)} models on page {page}. Ranks are task-scoped."
+            + (f" Next page: {result.next_page}." if result.next_page else "")
+            + (f" Note: {metric_note}." if metric_note else ""),
+        )
+
+    @server.tool(annotations=READ_ONLY, structured_output=True)
+    def list_benchmarks(
+        search: str | None = None,
+        task: str | None = None,
+        include_descendants: bool = False,
+        minimum_evaluations: int | None = None,
+        is_open: bool | None = None,
+        group_by_area: bool = False,
+        area: Area | None = None,
+        benchmarks_per_task: Annotated[int, Field(ge=1, le=10)] = 3,
+        order_by: Literal["trending", "name", "full_name", "created_at", "paper_count"]
+        | None = None,
+        order_direction: Direction = "asc",
+        page: Page = 1,
+        limit: Limit | None = None,
+    ) -> BenchmarkPage:
+        """List benchmarks for a task ranked by trend, filter them, or group them by area and task (`pwc benchmark list`). order_by=trending needs task (without it the list is ordered by name); area groups a whole area and is dropped when combined with task, search, or ordering filters. Follow with get_benchmark on the most relevant leaderboard."""
+        notes: list[str] = []
+        if order_by == "trending" and not task:
+            order_by = None
+            notes.append("order_by=trending needs task; ordered by name instead")
+        filtered = bool(
+            task
+            or search
+            or include_descendants
+            or is_open is not None
+            or order_by is not None
+            or order_direction != "asc"
+        )
+        if area is not None and filtered:
+            area = None
+            notes.append("area cannot be combined with filters; returned the filtered list")
+        grouped = group_by_area or area is not None
+        if minimum_evaluations is not None and minimum_evaluations < 1:
+            # The flat listing has no minimum by default and rejects 0 (it
+            # needs at least 1); the grouped one accepts 0 but defaults to 2.
+            minimum_evaluations = 0 if grouped else None
+        # Grouped listings are not paginated; the CLI rejects page/limit there.
+        data = run(
+            "list_benchmarks",
+            search=search,
+            task=task,
+            include_descendants=include_descendants,
+            minimum_evaluations=minimum_evaluations,
+            is_open=is_open,
+            group_by_area=group_by_area,
+            area=area,
+            benchmarks_per_task=benchmarks_per_task,
+            order_by=order_by,
+            order_direction=order_direction,
+            page=1 if grouped else page,
+            limit=None if grouped else (limit if limit is not None else MAX_ROWS),
+        )
+        if not isinstance(data, dict):
+            raise TypeError("benchmark listing did not contain a result document")
+        rows = _dicts(data.get("results"))
+        if grouped:
+            rows = _grouped_benchmarks(rows)
+        result = BenchmarkPage(
+            items=[benchmark_summary(item) for item in rows],
+            next_page=_next_page(data),
+            data=data,
+        )
+        summary = f"Found {len(result.items)} benchmarks."
+        if result.next_page:
+            summary += f" Next page: {result.next_page}."
+        for note in notes:
+            summary += f" Note: {note}."
+        return _tool_result(result, summary)
+
+    @server.prompt(name="find_papers", title="Find papers")
+    def find_papers_prompt(topic: str) -> str:
+        return (
+            f"Find papers about {topic!r}. Use semantic search for concepts, then "
+            "inspect the most relevant papers and cite their canonical URLs."
+        )
+
+    @server.prompt(name="compare_leaderboard", title="Compare a leaderboard")
+    def compare_leaderboard_prompt(benchmark: str) -> str:
+        return (
+            f"Inspect the {benchmark!r} benchmark. Explain metric direction and "
+            "evaluation settings, and do not compare ranks from different task scopes."
+        )
+
+    @server.prompt(name="survey_task", title="Survey a research task")
+    def survey_task_prompt(task: str) -> str:
+        return (
+            f"Survey the {task!r} task. Resolve its slug, inspect high-coverage "
+            "benchmarks, then summarize representative papers and methods."
+        )
+
+    @server.resource(
+        "pwc://papers/{paper}",
+        name="paper-info",
+        title="Paper information",
+        description="Canonical Papers With Code paper metadata.",
+        mime_type="application/json",
+    )
+    def paper_info_resource(paper: str) -> str:
+        return _structured_model(
+            get_paper_info(paper), PaperInfoResult
+        ).model_dump_json()
+
+    @server.resource(
+        "pwc://papers/{paper}/markdown",
+        name="paper-markdown",
+        title="Paper Markdown",
+        description="Complete stored Markdown for a paper when it fits one response.",
+        mime_type="text/markdown",
+    )
+    def paper_markdown_resource(paper: str) -> str:
+        result = read_paper(paper)
+        if result.truncated:
+            raise ValueError(
+                "paper is too large for one resource response; use read_paper with its continuation cursor"
+            )
+        return result.markdown
+
+    @server.resource(
+        "pwc://tasks/{task}",
+        name="task",
+        title="Research task",
+        description="Canonical Papers With Code task metadata and benchmarks.",
+        mime_type="application/json",
+    )
+    def task_resource(task: str) -> str:
+        return _structured_model(get_task(task), TaskResult).model_dump_json()
+
+    @server.resource(
+        "pwc://benchmarks/{benchmark}",
+        name="benchmark",
+        title="Benchmark leaderboard",
+        description="Canonical benchmark metadata and leading evaluations.",
+        mime_type="application/json",
+    )
+    def benchmark_resource(benchmark: str) -> str:
+        return _structured_model(
+            get_benchmark(benchmark), BenchmarkResult
+        ).model_dump_json()
+
+    return server

mcp_server/tests/conftest.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _cursor_secrets(monkeypatch):
+    monkeypatch.setenv("PWC_MCP_CURSOR_KEY_CURRENT", "test-current-cursor-secret")
+    monkeypatch.delenv("PWC_MCP_CURSOR_KEY_PREVIOUS", raising=False)

mcp_server/tests/test_app.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+import logging
+
+from pwc_mcp.app import (
+    MAX_RESPONSE_BODY_SIZE,
+    ResponseSizeLimitMiddleware,
+    _client_address,
+    create_app,
+)
+from starlette.applications import Starlette
+from starlette.datastructures import Headers
+from starlette.responses import Response
+from starlette.routing import Route
+from starlette.testclient import TestClient
+from test_server import StubCatalog
+
+
+def test_health_and_browser_origin_policy_are_explicit():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        allowed_origins=["https://chatgpt.com"],
+    )
+
+    with TestClient(app) as client:
+        health = client.get("/health")
+        rejected = client.post(
+            "/mcp",
+            headers={"Origin": "https://attacker.example"},
+            json={},
+        )
+        preflight = client.options(
+            "/mcp",
+            headers={
+                "Origin": "https://chatgpt.com",
+                "Access-Control-Request-Method": "POST",
+                "Access-Control-Request-Headers": "content-type,mcp-protocol-version,mcp-method,mcp-name",
+            },
+        )
+
+    assert health.status_code == 200
+    assert health.json() == {
+        "status": "ok",
+        "service": "pwc-mcp",
+        "version": "0.2.10",
+        "protocol": "2025-11-25",
+    }
+    assert rejected.status_code == 403
+    assert preflight.status_code == 200
+    assert preflight.headers["access-control-allow-origin"] == "https://chatgpt.com"
+
+
+def test_discovery_schema_and_bare_get_are_bounded():
+    app = create_app(StubCatalog(), allowed_hosts=["testserver"])
+
+    with TestClient(app) as client:
+        discovery = client.get("/.well-known/mcp")
+        schema = client.get("/docs")
+        bare_get = client.get("/mcp")
+
+    assert discovery.status_code == 200
+    assert discovery.json()["protocol_version"] == "2025-11-25"
+    assert discovery.json()["documentation_url"].endswith("/mcp/schema")
+    assert len(schema.json()["tools"]) == 21
+    assert bare_get.status_code == 405
+    assert bare_get.headers["allow"] == "POST"
+
+
+def test_wildcard_browser_origin_is_rejected_at_startup():
+    try:
+        create_app(StubCatalog(), allowed_origins=["*"])
+    except ValueError as error:
+        assert "must not contain a wildcard" in str(error)
+    else:
+        raise AssertionError("wildcard Origin was accepted")
+
+
+def test_rate_limit_is_content_free_and_returns_retry_metadata():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        request_limit=1,
+    )
+
+    with TestClient(app) as client:
+        first = client.post("/mcp", json={})
+        limited = client.post("/mcp", json={})
+
+    assert first.status_code != 429
+    assert limited.status_code == 429
+    assert limited.headers["retry-after"] == "60"
+    assert limited.json() == {"error": "rate_limit_exceeded"}
+
+
+def test_global_saturation_returns_retry_metadata():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        global_concurrency_limit=0,
+    )
+
+    with TestClient(app) as client:
+        response = client.post("/mcp", json={})
+
+    assert response.status_code == 503
+    assert response.headers["retry-after"] == "1"
+    assert response.json() == {"error": "server_saturated"}
+
+
+def test_semantic_limit_uses_body_tool_name_when_header_disagrees():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        request_limit=10,
+        semantic_limit=1,
+    )
+    request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "search_papers",
+            "arguments": {"query": "attention", "mode": "semantic"},
+        },
+    }
+
+    with TestClient(app) as client:
+        first = client.post("/mcp", json=request, headers={"MCP-Name": "get_task"})
+        limited = client.post("/mcp", json=request, headers={"MCP-Name": "get_task"})
+
+    assert first.status_code != 429
+    assert limited.status_code == 429
+
+
+def test_request_body_limit_is_enforced_before_protocol_parsing():
+    app = create_app(StubCatalog(), allowed_hosts=["testserver"])
+
+    with TestClient(app) as client:
+        response = client.post(
+            "/mcp",
+            content=b"x" * (2 * 1024 * 1024 + 1),
+            headers={"Content-Type": "application/json"},
+        )
+
+    assert response.status_code == 413
+    assert response.json() == {"error": "request_too_large"}
+
+
+def test_operational_telemetry_normalizes_untrusted_labels(caplog):
+    secret = "private unreleased project heliotrope"
+    app = create_app(StubCatalog(), allowed_hosts=["testserver"])
+
+    with caplog.at_level(logging.INFO), TestClient(app) as client:
+        client.post(
+            "/mcp",
+            json={
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "tools/call",
+                "params": {"name": secret, "arguments": {}},
+            },
+            headers={
+                "MCP-Name": secret,
+                "MCP-Protocol-Version": secret,
+            },
+        )
+
+    assert secret not in caplog.text
+    assert "tool=unknown" in caplog.text
+    assert "protocol=unknown" in caplog.text
+
+
+def test_one_http_endpoint_serves_modern_and_legacy_protocol_eras():
+    app = create_app(StubCatalog(), allowed_hosts=["testserver"])
+    modern_body = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "server/discover",
+        "params": {
+            "_meta": {
+                "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+                "io.modelcontextprotocol/clientInfo": {"name": "test", "version": "1"},
+                "io.modelcontextprotocol/clientCapabilities": {},
+            }
+        },
+    }
+    legacy_body = {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-11-25",
+            "capabilities": {},
+            "clientInfo": {"name": "test", "version": "1"},
+        },
+    }
+
+    with TestClient(app) as client:
+        modern = client.post(
+            "/mcp",
+            headers={
+                "Accept": "application/json, text/event-stream",
+                "MCP-Protocol-Version": "2026-07-28",
+                "Mcp-Method": "server/discover",
+            },
+            json=modern_body,
+        )
+        legacy = client.post(
+            "/mcp",
+            headers={"Accept": "application/json, text/event-stream"},
+            json=legacy_body,
+        )
+
+    assert modern.status_code == 200
+    assert modern.json()["result"]["supportedVersions"] == ["2026-07-28"]
+    assert modern.json()["result"]["cacheScope"] == "public"
+    assert legacy.status_code == 200
+    assert legacy.json()["result"]["protocolVersion"] == "2025-11-25"
+
+
+def test_proxy_identity_trusts_only_an_exact_loopback_peer():
+    headers = Headers({"x-forwarded-for": "203.0.113.9"})
+
+    assert (
+        _client_address({"client": ("127.0.0.1", 1234)}, headers, True) == "203.0.113.9"
+    )
+    assert _client_address({"client": ("::1", 1234)}, headers, True) == "203.0.113.9"
+    assert _client_address({"client": ("10.0.0.2", 1234)}, headers, True) == "10.0.0.2"
+    assert (
+        _client_address({"client": ("192.168.1.2", 1234)}, headers, True)
+        == "192.168.1.2"
+    )
+
+
+def test_loopback_first_party_clients_may_name_their_rate_limit_identity():
+    tagged = Headers({"x-pwc-mcp-client": "chat-0123abcd"})
+    assert (
+        _client_address({"client": ("127.0.0.1", 1)}, tagged, True)
+        == "client:chat-0123abcd"
+    )
+    assert (
+        _client_address({"client": ("::1", 1)}, tagged, True) == "client:chat-0123abcd"
+    )
+    # Proxied traffic always carries X-Forwarded-For, which wins over the tag.
+    proxied = Headers(
+        {"x-pwc-mcp-client": "chat-0123abcd", "x-forwarded-for": "203.0.113.9"}
+    )
+    assert _client_address({"client": ("127.0.0.1", 1)}, proxied, True) == "203.0.113.9"
+    # Remote peers, disabled trust, and malformed tags fall back to the address.
+    assert _client_address({"client": ("10.0.0.2", 1)}, tagged, True) == "10.0.0.2"
+    assert _client_address({"client": ("127.0.0.1", 1)}, tagged, False) == "127.0.0.1"
+    bad = Headers({"x-pwc-mcp-client": "spaces are/not ok"})
+    assert _client_address({"client": ("127.0.0.1", 1)}, bad, True) == "127.0.0.1"
+    long = Headers({"x-pwc-mcp-client": "a" * 129})
+    assert _client_address({"client": ("127.0.0.1", 1)}, long, True) == "127.0.0.1"
+
+
+def test_serialized_mcp_response_limit_fails_closed():
+    async def oversized(_request):
+        return Response(b"x" * (MAX_RESPONSE_BODY_SIZE + 1))
+
+    app = ResponseSizeLimitMiddleware(
+        Starlette(routes=[Route("/mcp", oversized, methods=["POST"])])
+    )
+    with TestClient(app) as client:
+        response = client.post("/mcp")
+
+    assert response.status_code == 503
+    assert response.json() == {"error": "response_too_large"}
+
+
+def test_hybrid_search_counts_toward_the_semantic_limit():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        semantic_limit=1,
+    )
+    body = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "search_papers",
+            "arguments": {"query": "attention", "mode": "hybrid"},
+        },
+    }
+
+    with TestClient(app) as client:
+        first = client.post("/mcp", json=body)
+        limited = client.post("/mcp", json=body)
+
+    assert first.status_code != 429
+    assert limited.status_code == 429
+
+
+def test_omitted_search_mode_defaults_to_hybrid_and_counts_toward_the_semantic_limit():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        semantic_limit=1,
+    )
+    body = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": "search_papers", "arguments": {"query": "attention"}},
+    }
+
+    with TestClient(app) as client:
+        first = client.post("/mcp", json=body)
+        limited = client.post("/mcp", json=body)
+
+    assert first.status_code != 429
+    assert limited.status_code == 429
+
+
+def test_keyword_search_does_not_count_toward_the_semantic_limit():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        semantic_limit=1,
+    )
+    body = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "search_papers",
+            "arguments": {"query": "attention", "mode": "keyword"},
+        },
+    }
+
+    with TestClient(app) as client:
+        first = client.post("/mcp", json=body)
+        second = client.post("/mcp", json=body)
+
+    assert first.status_code != 429
+    assert second.status_code != 429
+
+
+def test_rate_limits_are_env_configurable_with_hosted_defaults(monkeypatch):
+    from pwc_mcp.app import (
+        DEFAULT_GLOBAL_CONCURRENCY_LIMIT,
+        RateLimitMiddleware,
+        _int_env,
+        thread_limiter_tokens,
+    )
+
+    assert DEFAULT_GLOBAL_CONCURRENCY_LIMIT == 128
+    assert thread_limiter_tokens(8) == 40 and thread_limiter_tokens(256) == 256
+    monkeypatch.delenv("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", raising=False)
+    assert _int_env("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", 128) == 128
+    monkeypatch.setenv("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", "256")
+    assert _int_env("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", 128) == 256
+    for invalid in ("0", "abc", "-4", "10001"):
+        monkeypatch.setenv("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", invalid)
+        try:
+            _int_env("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", 128)
+        except ValueError:
+            continue
+        raise AssertionError(invalid)
+
+    monkeypatch.setenv("PWC_MCP_REQUEST_LIMIT", "7")
+    monkeypatch.setenv("PWC_MCP_SEMANTIC_LIMIT", "3")
+    monkeypatch.setenv("PWC_MCP_CONCURRENCY_LIMIT", "2")
+    monkeypatch.setenv("PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", "64")
+    app = create_app(StubCatalog(), allowed_hosts=["testserver"])
+    layer = app
+    while not isinstance(layer, RateLimitMiddleware):
+        layer = layer.app
+    assert (
+        layer.request_limit,
+        layer.semantic_limit,
+        layer.concurrency_limit,
+        layer.global_concurrency_limit,
+    ) == (7, 3, 2, 64)
+    with TestClient(app) as client:
+        assert client.get("/health").status_code in {200, 503}

mcp_server/tests/test_catalog.py

@@ -0,0 +1,575 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from pwc_cli.cli import UsageError
+from pwc_cli.transport import Response, ResponseError
+from pwc_mcp.catalog import (
+    CatalogClient,
+    PublicPaperMiss,
+    cache_ttl,
+    near_title,
+    normalize_title,
+)
+
+
+class StubTransport:
+    def __init__(self, routes):
+        self.routes = routes
+        self.calls = []
+
+    def get(self, path, params=None):
+        self.calls.append((path, params))
+        value = self.routes[path]
+        if isinstance(value, str):
+            return Response(value.encode(), {"content-type": "text/markdown"})
+        return Response(
+            json.dumps(value).encode(), {"content-type": "application/json"}
+        )
+
+
+def test_catalog_normalizes_paper_urls_and_caches_identical_reads():
+    transport = StubTransport(
+        {
+            "papers/1706.03762": {"id": "755", "title": "Attention Is All You Need"},
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    first = catalog.query(
+        ("paper", "info"),
+        {"paper": "https://arxiv.org/pdf/1706.03762v7.pdf", "include_resources": True},
+    )
+    second = catalog.query(
+        ("paper", "info"),
+        {
+            "paper": "https://huggingface.co/papers/1706.03762",
+            "include_resources": True,
+        },
+    )
+
+    assert first == second
+    assert transport.calls == [("papers/1706.03762", {"include_resources": True})]
+
+
+def test_catalog_reads_one_version_bound_markdown_chunk_per_call():
+    version = "a" * 64
+
+    class ChunkTransport:
+        def __init__(self):
+            self.calls = []
+
+        def get(self, path, params=None):
+            self.calls.append((path, params))
+            if params["offset"] == 0:
+                return Response(
+                    "α first".encode(),
+                    {
+                        "x-pwc-truncated": "1",
+                        "x-pwc-content-version": version,
+                        "x-pwc-next-offset": "8",
+                    },
+                )
+            return Response(
+                b" terminal",
+                {
+                    "x-pwc-truncated": "0",
+                    "x-pwc-content-version": version,
+                },
+            )
+
+    transport = ChunkTransport()
+    catalog = CatalogClient(transport=transport)
+    first = catalog.read_paper_chunk("1706.03762", limit=65_536)
+    second = catalog.read_paper_chunk(
+        "1706.03762",
+        offset=first.next_offset,
+        content_version=first.content_version,
+        limit=65_536,
+        resolved=True,
+    )
+
+    assert first.markdown == "α first"
+    assert first.next_offset == 8
+    assert second.markdown == " terminal"
+    assert second.next_offset is None
+    assert transport.calls == [
+        (
+            "research/papers/1706.03762/read",
+            {"offset": 0, "limit": 65_536, "content_version": None},
+        ),
+        (
+            "research/papers/1706.03762/read",
+            {"offset": 8, "limit": 65_536, "content_version": version},
+        ),
+    ]
+
+
+def test_catalog_caches_versioned_chunks_and_rejects_nonadvancing_offsets():
+    version = "b" * 64
+
+    class ChunkTransport:
+        def __init__(self):
+            self.calls = 0
+
+        def get(self, _path, _params=None):
+            self.calls += 1
+            return Response(
+                b"data",
+                {
+                    "x-pwc-truncated": "1",
+                    "x-pwc-content-version": version,
+                    "x-pwc-next-offset": "4",
+                },
+            )
+
+    transport = ChunkTransport()
+    catalog = CatalogClient(transport=transport)
+    with pytest.raises(ResponseError, match="did not advance"):
+        catalog.read_paper_chunk(
+            "1706.03762",
+            offset=4,
+            content_version=version,
+            resolved=True,
+        )
+    assert transport.calls == 1
+
+
+def test_catalog_versioned_chunk_cache_avoids_repeated_upstream_reads():
+    version = "c" * 64
+
+    class ChunkTransport:
+        def __init__(self):
+            self.calls = 0
+
+        def get(self, _path, _params=None):
+            self.calls += 1
+            return Response(
+                b"done",
+                {
+                    "x-pwc-truncated": "0",
+                    "x-pwc-content-version": version,
+                },
+            )
+
+    transport = ChunkTransport()
+    catalog = CatalogClient(transport=transport)
+    first = catalog.read_paper_chunk(
+        "1706.03762",
+        offset=8,
+        content_version=version,
+        resolved=True,
+    )
+    second = catalog.read_paper_chunk(
+        "1706.03762",
+        offset=8,
+        content_version=version,
+        resolved=True,
+    )
+
+    assert first == second
+    assert transport.calls == 1
+
+
+def test_catalog_resolves_exact_titles_and_rejects_ambiguous_titles():
+    transport = StubTransport(
+        {
+            "papers/search": {
+                "results": [
+                    {"id": "1", "arxiv_id": "1111.11111", "title": "Same Title"},
+                    {"id": "2", "arxiv_id": "2222.22222", "title": "Same Title"},
+                ]
+            }
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    with pytest.raises(ResponseError, match="ambiguous"):
+        catalog.query(("paper", "lineage", "list"), {"paper": "Same Title"})
+
+
+def test_catalog_resolves_pwc_urls_and_dotted_legacy_arxiv_ids():
+    transport = StubTransport(
+        {
+            "papers/search": {
+                "results": [
+                    {
+                        "id": "755",
+                        "arxiv_id": "1706.03762",
+                        "title": "Attention Is All You Need",
+                    }
+                ]
+            },
+            "papers/1706.03762": {"id": "755"},
+            "papers/math.GT%2F0309136": {"id": "900"},
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    assert catalog.query(
+        ("paper", "info"),
+        {"paper": "https://paperswithcode.co/paper/attention-is-all-you-need"},
+    ) == {"id": "755"}
+    assert catalog.query(("paper", "info"), {"paper": "math.GT/0309136"}) == {
+        "id": "900"
+    }
+
+
+def test_catalog_checks_later_search_pages_for_ambiguous_exact_titles():
+    class PaginatedTransport:
+        def get(self, path, params=None):
+            assert path == "papers/search"
+            page = params["page"]
+            payload = {
+                "results": [
+                    {
+                        "id": str(page),
+                        "arxiv_id": f"1111.1111{page}",
+                        "title": "Same Title",
+                    }
+                ],
+                "next_page": 2 if page == 1 else None,
+            }
+            return Response(json.dumps(payload).encode(), {})
+
+    catalog = CatalogClient(transport=PaginatedTransport())
+
+    with pytest.raises(ResponseError, match="ambiguous"):
+        catalog.query(("paper", "lineage", "list"), {"paper": "Same Title"})
+
+
+def test_catalog_fails_closed_when_paper_filters_are_not_confirmed():
+    transport = StubTransport({"papers/": {"results": [], "applied_filters": {}}})
+    catalog = CatalogClient(transport=transport)
+
+    with pytest.raises(ResponseError, match="did not confirm"):
+        catalog.query(("paper", "list"), {"task": "image-classification"})
+
+
+def test_catalog_query_runs_cli_commands_with_per_path_cache_lifetimes():
+    transport = StubTransport(
+        {
+            "datasets/": {"results": [{"id": "72", "name": "ImageNet-1k"}]},
+            "datasets/72/evaluations/": {
+                "count": 1,
+                "results": [{"id": "1", "model_name": "A", "metrics": {"top1": 80}}],
+            },
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    first = catalog.query(("benchmark",), {"name": "ImageNet-1k", "limit": 5})
+    second = catalog.query(("benchmark",), {"name": "imagenet-1k", "limit": 5})
+
+    assert first == second
+    assert first["results"][0]["model_name"] == "A"
+    assert first["count"] == 1
+    # The second lookup differs only in the search text; the identical
+    # evaluation request is served from the shared cache.
+    assert [path for path, _params in transport.calls] == [
+        "datasets/",
+        "datasets/72/evaluations/",
+        "datasets/",
+    ]
+    assert cache_ttl("papers/search") == 60
+    assert cache_ttl("tasks/1/page") == 600
+    assert cache_ttl("datasets/72/evaluations/") == 300
+
+
+def test_catalog_query_reports_cli_usage_errors_without_upstream_calls():
+    transport = StubTransport({})
+    catalog = CatalogClient(transport=transport)
+
+    with pytest.raises(UsageError, match="--limit must be 1-100"):
+        catalog.query(("search",), {"query": "x", "limit": 0})
+    with pytest.raises(UsageError, match="not a read-only"):
+        catalog.query(("skills", "add"), {})
+    assert transport.calls == []
+
+
+def test_catalog_canonicalises_numeric_ids_of_arxiv_papers():
+    transport = StubTransport(
+        {
+            "papers/86122": {"id": "86122", "arxiv_id": "2505.18132v1"},
+            "papers/2505.18132": {"id": "86122", "title": "BiggerGait"},
+            "papers/4242": {"id": "4242", "arxiv_id": None, "source": "external"},
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    # List tools hand out numeric IDs for arXiv papers too; the Markdown route
+    # only knows arXiv papers by arXiv ID, so numeric references canonicalise.
+    assert catalog.resolve_paper("86122") == "2505.18132"
+    assert catalog.query(("paper", "info"), {"paper": "86122"}) == {
+        "id": "86122",
+        "title": "BiggerGait",
+    }
+    # External papers have no arXiv ID and keep their numeric reference.
+    assert catalog.resolve_paper("4242") == "4242"
+    assert transport.calls[0] == ("papers/86122", {})
+
+
+def test_catalog_rejects_unsupported_urls_without_searching():
+    transport = StubTransport({})
+    catalog = CatalogClient(transport=transport)
+
+    for url in (
+        "https://doi.org/10.1007/s10479-024-06277-x",
+        "https://aclanthology.org/2026.acl-long.200/",
+    ):
+        with pytest.raises(ResponseError, match="Paper URL not supported"):
+            catalog.resolve_paper(url)
+    assert transport.calls == []
+
+
+def test_catalog_distinguishes_missing_papers_from_missing_markdown():
+    from pwc_cli.transport import HTTPStatusError
+
+    class MissingTransport:
+        def __init__(self, paper_exists):
+            self.paper_exists = paper_exists
+
+        def get(self, path, params=None):
+            if path.endswith("/read"):
+                raise HTTPStatusError(404, "Paper Markdown was not found")
+            if self.paper_exists:
+                return Response(b'{"id": "1"}', {})
+            raise HTTPStatusError(404, "No paper found")
+
+    with pytest.raises(ResponseError, match="Paper not found: 2308.10195"):
+        CatalogClient(transport=MissingTransport(False)).read_paper_chunk(
+            "2308.10195", resolved=True
+        )
+    with pytest.raises(HTTPStatusError) as missing_markdown:
+        CatalogClient(transport=MissingTransport(True)).read_paper_chunk(
+            "2505.18132", resolved=True
+        )
+    assert missing_markdown.value.status == 404
+
+
+def test_catalog_reports_titles_missing_from_an_empty_search_as_not_found():
+    # The public API answers an unknown title with an empty result list; that
+    # must surface as "title not found", not as a malformed response.
+    transport = StubTransport(
+        {
+            "papers/search": {
+                "next_page": None,
+                "previous_page": None,
+                "results": [],
+                "applied_filters": {},
+            }
+        }
+    )
+    catalog = CatalogClient(transport=transport)
+
+    with pytest.raises(ResponseError, match="Paper title not found: Dropout"):
+        catalog.resolve_paper("Dropout: A Simple Way to Prevent Overfitting")
+    # One phrase query, then one plain keyword query as the fallback.
+    assert [params["q"] for _path, params in transport.calls] == [
+        '"Dropout: A Simple Way to Prevent Overfitting"',
+        "Dropout: A Simple Way to Prevent Overfitting",
+    ]
+
+
+EXACT_TITLE_ROW = {"id": "755", "arxiv_id": "1706.03762", "title": "Attention Is All You Need"}
+
+
+class TitleSearchTransport:
+    """Keyword search whose plain results never end; the phrase query is small."""
+
+    def __init__(self, *, phrase_results, plain_has_exact):
+        self.phrase_results = phrase_results
+        self.plain_has_exact = plain_has_exact
+        self.calls = []
+
+    def get(self, path, params=None):
+        params = dict(params or {})
+        self.calls.append((path, params))
+        assert path == "papers/search"
+        page = params["page"]
+        if params["q"].startswith('"'):
+            body = {"results": self.phrase_results, "next_page": None}
+        else:
+            rows = [
+                {"id": str(page * 100 + i), "arxiv_id": f"2{page:03d}.{i:05d}", "title": f"Attention {i}"}
+                for i in range(100)
+            ]
+            if self.plain_has_exact and page == 1:
+                rows[0] = EXACT_TITLE_ROW
+            body = {"results": rows, "next_page": page + 1}
+        return Response(json.dumps(body).encode(), {"content-type": "application/json"})
+
+
+def test_catalog_resolves_common_word_titles_through_one_phrase_query():
+    # "Attention Is All You Need" has over a thousand keyword hits; paging
+    # through them used to end in "Too many results" although the exact title
+    # was the first result.
+    transport = TitleSearchTransport(
+        phrase_results=[
+            EXACT_TITLE_ROW,
+            {"id": "9", "arxiv_id": "2010.13154", "title": "Attention is All You Need in Speech Separation"},
+        ],
+        plain_has_exact=True,
+    )
+    catalog = CatalogClient(transport=transport)
+
+    assert catalog.resolve_paper("Attention Is All You Need") == "1706.03762"
+    assert [params["q"] for _path, params in transport.calls] == ['"Attention Is All You Need"']
+
+
+def test_catalog_keeps_exact_matches_found_before_the_page_budget_runs_out():
+    transport = TitleSearchTransport(phrase_results=[], plain_has_exact=True)
+    catalog = CatalogClient(transport=transport)
+
+    assert catalog.resolve_paper("Attention Is All You Need") == "1706.03762"
+    assert len(transport.calls) == 11
+
+    inconclusive = CatalogClient(
+        transport=TitleSearchTransport(phrase_results=[], plain_has_exact=False)
+    )
+    with pytest.raises(ResponseError, match="Too many results"):
+        inconclusive.resolve_paper("Attention Is All You Need")
+
+
+def test_catalog_resolves_a_unique_short_name_before_the_title_colon():
+    # Production chat: get_paper_info("MuseTalk") failed although the catalog
+    # holds "MuseTalk: Real-Time High-Fidelity Video Dubbing ..." (2410.10122).
+    musetalk = {
+        "id": "90",
+        "arxiv_id": "2410.10122",
+        "title": "MuseTalk: Real-Time High-Fidelity Video Dubbing via Spatio-Temporal Sampling",
+    }
+    citing = {"id": "91", "arxiv_id": "2501.00001", "title": "Beyond MuseTalk: Faster Dubbing"}
+    transport = TitleSearchTransport(phrase_results=[musetalk, citing], plain_has_exact=False)
+    catalog = CatalogClient(transport=transport)
+
+    assert catalog.resolve_paper("MuseTalk") == "2410.10122"
+    assert catalog.resolve_paper("musetalk") == "2410.10122"
+
+    twins = [musetalk, {**musetalk, "id": "92", "arxiv_id": "2502.00002"}]
+    ambiguous = CatalogClient(
+        transport=TitleSearchTransport(phrase_results=twins, plain_has_exact=False)
+    )
+    with pytest.raises(ResponseError, match="Paper title is ambiguous: MuseTalk"):
+        ambiguous.resolve_paper("MuseTalk")
+
+
+def test_catalog_resolves_a_unique_near_match_of_a_full_title():
+    # Production chat: get_paper_info("BEIR: A Heterogeneous Benchmark ...")
+    # failed although the catalog holds the arXiv spelling "Heterogenous"
+    # (2104.08663), which keyword search returns first.
+    beir = {
+        "id": "5505",
+        "arxiv_id": "2104.08663",
+        "title": "BEIR: A Heterogenous Benchmark for Zero-shot Evaluation of Information Retrieval Models",
+    }
+    beir_nl = {
+        "id": "93",
+        "arxiv_id": "2412.08329",
+        "title": "BEIR-NL: Zero-shot Information Retrieval Benchmark for the Dutch Language",
+    }
+    catalog = CatalogClient(
+        transport=TitleSearchTransport(phrase_results=[beir, beir_nl], plain_has_exact=False)
+    )
+
+    assert catalog.resolve_paper(
+        "BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models"
+    ) == "2104.08663"
+
+    twins = [beir, {**beir, "id": "94", "arxiv_id": "2502.00003"}]
+    ambiguous = CatalogClient(
+        transport=TitleSearchTransport(phrase_results=twins, plain_has_exact=False)
+    )
+    with pytest.raises(ResponseError, match="Paper title is ambiguous"):
+        ambiguous.resolve_paper(
+            "BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models"
+        )
+
+
+def test_near_title_rejects_short_names_and_other_editions():
+    assert near_title(
+        normalize_title("BEIR: A Heterogenous Benchmark for Zero-shot Evaluation"),
+        normalize_title("BEIR: A Heterogeneous Benchmark for Zero-shot Evaluation"),
+    )
+    assert not near_title(normalize_title("MuseTalks"), normalize_title("MuseTalk"))
+    assert not near_title(
+        normalize_title("The Llama 3 Herd of Language Foundation Models"),
+        normalize_title("The Llama 4 Herd of Language Foundation Models"),
+    )
+    assert not near_title(
+        normalize_title("Deep Residual Learning for Image Recognition"),
+        normalize_title("Deep Residual Learning for Video Recognition"),
+    )
+
+
+def test_catalog_reads_public_metadata_and_caches_lookups_including_misses():
+    from pwc_cli.transport import HTTPStatusError
+
+    class PublicTransport:
+        def __init__(self):
+            self.calls = []
+
+        def get(self, path, params=None):
+            self.calls.append((path, params))
+            if path == "papers/2610.18869/public-metadata":
+                return Response(
+                    json.dumps({"in_catalog": False, "title": "Found"}).encode(), {}
+                )
+            if path == "papers/public-metadata/search":
+                title = params["title"]
+                if title == "Down Title":
+                    raise HTTPStatusError(503, "unavailable")
+                if title == "BERT":
+                    raise HTTPStatusError(400, "title too short")
+                if title == "Some Title":
+                    return Response(
+                        json.dumps({"in_catalog": False, "title": "Some title"}).encode(),
+                        {},
+                    )
+                raise HTTPStatusError(404, "no exact title")
+            if path.startswith("papers/Down/"):
+                raise HTTPStatusError(503, "unavailable")
+            if "%20" in path or path == "papers/BERT/public-metadata":
+                raise HTTPStatusError(400, "titles are not identifiers")
+            raise HTTPStatusError(404, "Paper not found")
+
+    transport = PublicTransport()
+    catalog = CatalogClient(transport=transport)
+
+    assert catalog.public_paper(" 2610.18869 ")["title"] == "Found"
+    assert catalog.public_paper("2610.18869")["title"] == "Found"
+    assert catalog.public_paper("10.1/x") == PublicPaperMiss("identifier")
+    assert catalog.public_paper("10.1/x") == PublicPaperMiss("identifier")
+    # Titles the identifier route rejects are searched as exact titles.
+    assert catalog.public_paper("Some Title") == {
+        "in_catalog": False,
+        "title": "Some title",
+        "requested_title": "Some Title",
+    }
+    assert catalog.public_paper("Some Title")["title"] == "Some title"
+    assert catalog.public_paper("Unknown Title") == PublicPaperMiss("title")
+    assert catalog.public_paper("Unknown Title") == PublicPaperMiss("title")
+    assert catalog.public_paper("BERT") == PublicPaperMiss("unsupported")
+    # Upstream failures are best effort and not cached as misses.
+    assert catalog.public_paper("Down") == PublicPaperMiss("unavailable")
+    assert catalog.public_paper("Down") == PublicPaperMiss("unavailable")
+    assert catalog.public_paper("Down Title") == PublicPaperMiss("unavailable")
+    assert catalog.public_paper("Down Title") == PublicPaperMiss("unavailable")
+    search = "papers/public-metadata/search"
+    assert transport.calls == [
+        ("papers/2610.18869/public-metadata", None),
+        ("papers/10.1/x/public-metadata", None),
+        ("papers/Some%20Title/public-metadata", None),
+        (search, {"title": "Some Title"}),
+        ("papers/Unknown%20Title/public-metadata", None),
+        (search, {"title": "Unknown Title"}),
+        ("papers/BERT/public-metadata", None),
+        (search, {"title": "BERT"}),
+        ("papers/Down/public-metadata", None),
+        ("papers/Down/public-metadata", None),
+        ("papers/Down%20Title/public-metadata", None),
+        (search, {"title": "Down Title"}),
+        ("papers/Down%20Title/public-metadata", None),
+        (search, {"title": "Down Title"}),
+    ]

mcp_server/tests/test_cursors.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import pytest
+from pwc_mcp.cursors import CursorCodec, CursorReferenceMismatch, CursorState
+
+
+def _state(*, expires_at: int = 4600) -> CursorState:
+    return CursorState(
+        reference="Attention Is All You Need",
+        paper="1706.03762",
+        source="arxiv",
+        content_version="a" * 64,
+        offset=65536,
+        limit=65536,
+        expires_at=expires_at,
+    )
+
+
+def test_cursor_round_trip_and_replay_are_stable():
+    codec = CursorCodec("current-secret", now=lambda: 1000)
+    token = codec.encode(_state())
+
+    assert codec.decode(token, reference="Attention Is All You Need") == _state()
+    assert codec.decode(token, reference="Attention Is All You Need") == _state()
+
+
+def test_cursor_rejects_tampering_another_reference_and_expiry():
+    codec = CursorCodec("current-secret", now=lambda: 1000)
+    token = codec.encode(_state(expires_at=1001))
+
+    with pytest.raises(ValueError, match="invalid continuation cursor"):
+        codec.decode(token[:-1] + ("A" if token[-1] != "A" else "B"), reference="Attention Is All You Need")
+    with pytest.raises(ValueError, match="invalid continuation cursor"):
+        codec.decode(token, reference="Another paper")
+
+    expired = CursorCodec("current-secret", now=lambda: 1002)
+    with pytest.raises(ValueError, match="expired continuation cursor"):
+        expired.decode(token, reference="Attention Is All You Need")
+
+
+def test_cursor_rotation_accepts_previous_key_without_extending_expiry():
+    old = CursorCodec("old-secret", now=lambda: 1000)
+    token = old.encode(_state(expires_at=1200))
+    rotated = CursorCodec(
+        "new-secret", previous_secret="old-secret", now=lambda: 1100
+    )
+
+    assert rotated.decode(token, reference="Attention Is All You Need").expires_at == 1200
+
+
+def test_cursor_rejects_oversized_or_invalid_state():
+    codec = CursorCodec("current-secret", now=lambda: 1000)
+
+    with pytest.raises(ValueError, match="invalid continuation cursor"):
+        codec.decode("x" * 4096, reference="paper")
+    with pytest.raises(ValueError, match="invalid continuation cursor"):
+        codec.encode(_state(expires_at=1000))
+    with pytest.raises(ValueError, match="cursor secret"):
+        CursorCodec("")
+
+
+def test_cursor_for_another_reference_reports_the_mismatch_with_its_state():
+    codec = CursorCodec("current-secret", now=lambda: 1000)
+    token = codec.encode(_state())
+
+    with pytest.raises(CursorReferenceMismatch, match="invalid continuation cursor") as caught:
+        codec.decode(token, reference="755")
+    assert caught.value.state == _state()
+
+    # Tampering and expiry still win over the reference check.
+    expired = CursorCodec("current-secret", now=lambda: 5000)
+    with pytest.raises(ValueError, match="expired continuation cursor"):
+        expired.decode(token, reference="755")

mcp_server/tests/test_parity.py

@@ -0,0 +1,106 @@
+"""Every read-only CLI command is a tool, and every research flag a parameter."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from mcp.client import Client
+from pwc_cli import queries
+from pwc_mcp.server import (
+    ENTITY_PARAMETERS,
+    MCP_ONLY_PARAMETERS,
+    PARAMETER_NAMES,
+    TOOL_COMMANDS,
+    build_server,
+    cli_options,
+)
+from test_server import StubCatalog
+
+# Deliberate default divergences from the CLI, documented in README.md: the
+# hosted service caps rows per response at 25 (list_benchmarks and list_tasks
+# leave the row count to the server instead of the CLI's 50).
+DEFAULT_EXCEPTIONS = {
+    ("list_benchmarks", "limit"): None,
+    ("list_methods", "limit"): 25,
+    ("list_tasks", "limit"): None,
+}
+# argparse placeholders for "not given"; the MCP schema spells these as null.
+UNSET_DEFAULTS = (None, argparse.SUPPRESS, (), [])
+
+
+def _tools():
+    async def exercise():
+        async with Client(build_server(StubCatalog())) as client:
+            return {tool.name: tool for tool in (await client.list_tools()).tools}
+
+    return asyncio.run(exercise())
+
+
+def _enum_values(schema, root):
+    if "$ref" in schema:
+        schema = root["$defs"][schema["$ref"].rsplit("/", 1)[1]]
+    values = list(schema.get("enum") or [])
+    for branch in schema.get("anyOf") or []:
+        values.extend(_enum_values(branch, root))
+    return values
+
+
+def _mcp_name(tool: str, destination: str) -> str:
+    if destination == "name":
+        return ENTITY_PARAMETERS[tool]
+    return PARAMETER_NAMES.get(destination, destination)
+
+
+def test_every_read_only_cli_command_has_exactly_one_tool():
+    assert sorted(TOOL_COMMANDS.values()) == sorted(queries.READ_ONLY_COMMANDS)
+    assert len(set(TOOL_COMMANDS.values())) == len(TOOL_COMMANDS)
+
+
+def test_every_cli_research_flag_is_a_tool_parameter_and_vice_versa():
+    tools = _tools()
+
+    assert set(tools) == set(TOOL_COMMANDS)
+    for tool, command in TOOL_COMMANDS.items():
+        cli = queries.query_options(command)
+        schema = tools[tool].input_schema
+        parameters = set(schema["properties"]) - MCP_ONLY_PARAMETERS.get(
+            tool, frozenset()
+        )
+        mapped = cli_options(tool, **dict.fromkeys(parameters))
+
+        assert set(mapped) == set(cli), tool
+        for destination, action in cli.items():
+            parameter = _mcp_name(tool, destination)
+            property_schema = schema["properties"][parameter]
+            if isinstance(action, argparse._StoreTrueAction):
+                assert property_schema.get("type") == "boolean", (tool, parameter)
+            elif action.choices and set(action.choices) != {"true", "false"}:
+                assert set(action.choices) <= set(
+                    _enum_values(property_schema, schema)
+                ), (
+                    tool,
+                    parameter,
+                )
+            if not action.option_strings or destination == "name":
+                assert parameter in schema["required"], (tool, parameter)
+            # Same arguments must mean the same query through `pwc` and the MCP
+            # tools, so every CLI default is the tool default unless documented.
+            if action.default not in UNSET_DEFAULTS:
+                expected = DEFAULT_EXCEPTIONS.get((tool, parameter), action.default)
+                assert property_schema.get("default") == expected, (tool, parameter)
+
+
+def test_paper_references_and_entity_names_are_required_everywhere():
+    tools = _tools()
+
+    for tool, entity in ENTITY_PARAMETERS.items():
+        assert tools[tool].input_schema["required"] == [entity]
+    for tool in (
+        "get_paper_info",
+        "get_paper_evaluations",
+        "read_paper",
+        "get_related_papers",
+        "get_paper_lineage",
+    ):
+        assert tools[tool].input_schema["required"] == ["paper"]

mcp_server/tests/test_server.py

@@ -0,0 +1,1176 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import pytest
+from mcp.client import Client
+from pwc_cli.cli import UsageError
+from pwc_cli.transport import HTTPStatusError, ResponseError
+from pwc_mcp.catalog import PaperMarkdownChunk, PublicPaperMiss
+from pwc_mcp.models import paper_detail
+from pwc_mcp.server import TOOL_COMMANDS, build_server
+
+PAPER_ROW = {
+    "id": "755",
+    "arxiv_id": "1706.03762",
+    "title": "Attention Is All You Need",
+    "authors": ["Ashish Vaswani"],
+    "published": "2017-06-12",
+    "citation_count": 190_373,
+    "url_abs": "https://arxiv.org/abs/1706.03762v7",
+    "has_official_implementation": True,
+    "code_repository_count": 595,
+}
+PAPER_PAGE = {"next_page": 2, "results": [PAPER_ROW]}
+PAPER_INFO = {
+    **PAPER_ROW,
+    "abstract": "A transformer architecture.",
+    "url_pdf": "https://arxiv.org/pdf/1706.03762v7.pdf",
+    "tasks": [
+        {"id": "6", "name": "Machine Translation", "slug": "machine-translation"}
+    ],
+    "methods": [{"id": "1", "name": "Transformer", "slug": "transformer"}],
+    "repositories": [
+        {"url": "https://github.com/tensorflow/tensor2tensor", "is_official": True}
+    ],
+    "project_pages": ["https://example.test/transformer"],
+    "hf_models": ["https://huggingface.co/google-t5/t5-base"],
+    "hf_datasets": [],
+    "hf_spaces": [],
+}
+PAPER_EVALUATION = {
+    "id": "40",
+    "dataset_name": "WMT2014 English-German",
+    "task_name": "Machine Translation",
+    "model_name": "Transformer Big",
+    "metrics": {"BLEU score": 28.4},
+    "best_metric": "BLEU score",
+    "best_rank": 3,
+    "is_open": True,
+    "num_parameters": 213_000_000,
+    "result_url": "https://example.test/result",
+}
+EVALUATION_ROW = {
+    "id": "10",
+    "model_name": "ExampleNet",
+    "harness": "timm",
+    "metrics": {"Accuracy": 90.1},
+    "best_metric": "Accuracy",
+    "best_rank": 1,
+    "task_name": "Image Classification",
+    "paper_id": "755",
+    "paper_title": "Attention Is All You Need",
+    "paper_arxiv_id": "1706.03762",
+    "paper_published_date": "2017-06-12",
+    "is_open": True,
+    "num_parameters": 1000,
+}
+BENCHMARK = {
+    "id": "72",
+    "name": "ImageNet-1k",
+    "slug": "imagenet-1k",
+    "paper_count": 124,
+}
+TASK = {
+    "id": "1",
+    "name": "Image Classification",
+    "slug": "image-classification",
+    "description": "Assign a class to an image.",
+    "paper_count": 2343,
+}
+METHOD = {
+    "id": "2",
+    "name": "Transformer",
+    "slug": "transformer",
+    "full_name": "Transformer",
+    "description": "Attention-based architecture.",
+    "introduced_year": 2017,
+    "source_paper_id": "755",
+    "source_url": "/paper/1706.03762",
+    "source_title": "Attention Is All You Need",
+    "paper_count": 13505,
+}
+CONFERENCE = {"slug": "cvpr-2025", "name": "CVPR 2025", "year": 2025, "paper_count": 3}
+ORGANIZATION = {"id": "4", "slug": "nvidia", "name": "NVIDIA", "paper_count": 900}
+FRAMEWORK = {"id": "7", "slug": "vllm", "name": "vLLM", "platforms": ["gpu"]}
+GROUPED_BENCHMARKS = {
+    "results": [
+        {
+            "id": "1",
+            "name": "Vision",
+            "tasks": [
+                {
+                    "slug": "image-classification",
+                    "benchmarks": [
+                        {
+                            "id": "72",
+                            "name": "ImageNet-1k",
+                            "slug": "imagenet-1k",
+                            "evaluation_count": 124,
+                        }
+                    ],
+                }
+            ],
+        }
+    ]
+}
+
+PAYLOADS = {
+    ("search",): PAPER_PAGE,
+    ("paper", "list"): PAPER_PAGE,
+    # The recent and trending endpoints return a bare list of papers.
+    ("paper", "recent"): [PAPER_ROW],
+    ("paper", "trending"): [PAPER_ROW],
+    ("paper", "related"): {"results": [PAPER_ROW]},
+    ("paper", "evaluations"): {
+        "count": 1,
+        "page": 1,
+        "next_page": 2,
+        "results": [EVALUATION_ROW],
+    },
+    ("paper", "lineage", "list"): {
+        "paper": {
+            "id": 755,
+            "reference": "1706.03762",
+            "title": "Attention Is All You Need",
+        },
+        "predecessors": [],
+        "successors": [{"id": 900, "reference": "2001.00001", "title": "A Follow-up"}],
+    },
+    ("task",): {
+        "task": TASK,
+        "area": {"id": "1", "name": "Vision"},
+        "parents": [],
+        "children": [],
+        "benchmarks": [BENCHMARK],
+        "common_methods": [METHOD],
+        "papers": [PAPER_ROW],
+        "paper_count": 2343,
+    },
+    ("task", "list"): {"count": 1, "results": [TASK]},
+    ("method",): {"method": METHOD, "area": {"id": "1", "name": "Vision"}},
+    ("method", "list"): {"count": 1, "results": [METHOD]},
+    ("conference",): CONFERENCE,
+    ("conference", "list"): {"count": 1, "results": [CONFERENCE]},
+    ("organization",): ORGANIZATION,
+    ("organization", "list"): {"count": 1, "results": [ORGANIZATION]},
+    ("framework",): FRAMEWORK,
+    ("framework", "list"): {"count": 1, "results": [FRAMEWORK]},
+    ("benchmark",): {
+        "benchmark": {"id": "72", "name": "ImageNet-1k", "slug": "imagenet-1k"},
+        "count": 1,
+        "matched_count": 1,
+        "page": 1,
+        "next_page": 2,
+        "results": [EVALUATION_ROW],
+    },
+    ("benchmark", "list"): {"next_page": None, "results": [BENCHMARK]},
+}
+
+
+class StubCatalog:
+    """Records the CLI command and options each tool requests."""
+
+    def __init__(self):
+        self.queries: list[tuple[tuple[str, ...], dict]] = []
+        self.resolve_calls = 0
+        self.read_calls = []
+
+    def resolve_paper(self, paper: str):
+        self.resolve_calls += 1
+        assert paper == "1706.03762"
+        return paper
+
+    def read_paper_chunk(
+        self,
+        paper: str,
+        *,
+        offset: int = 0,
+        content_version: str | None = None,
+        limit: int = 65_536,
+        resolved: bool = False,
+    ):
+        assert paper == "1706.03762"
+        assert resolved is True
+        version = "a" * 64
+        assert content_version in {None, version}
+        self.read_calls.append((offset, content_version, limit))
+        raw = b"abcdefgh"
+        markdown = raw[offset : offset + limit].decode()
+        next_offset = (
+            offset + len(markdown) if offset + len(markdown) < len(raw) else None
+        )
+        return PaperMarkdownChunk(
+            paper=paper,
+            source="arxiv",
+            markdown=markdown,
+            content_version=version,
+            next_offset=next_offset,
+        )
+
+    def query(self, command, options):
+        self.queries.append((tuple(command), dict(options)))
+        if command == ("paper", "info"):
+            payload = dict(PAPER_INFO)
+            if options.get("include_evals"):
+                payload["evaluations"] = {"count": 1, "results": [PAPER_EVALUATION]}
+            return payload
+        if command == ("benchmark", "list") and (
+            options.get("group_by_area") or options.get("area")
+        ):
+            return GROUPED_BENCHMARKS
+        return PAYLOADS[tuple(command)]
+
+    def public_paper(self, reference: str):
+        return PublicPaperMiss("identifier")
+
+    def options(self, command):
+        return next(options for called, options in self.queries if called == command)
+
+
+def _call(catalog, requests, **server_options):
+    async def exercise():
+        async with Client(build_server(catalog, **server_options)) as client:
+            results = []
+            for name, arguments in requests:
+                results.append(await client.call_tool(name, arguments))
+            return results
+
+    return asyncio.run(exercise())
+
+
+def test_search_papers_is_a_read_only_structured_tool():
+    catalog = StubCatalog()
+
+    async def exercise():
+        async with Client(build_server(catalog)) as client:
+            tools = {tool.name: tool for tool in (await client.list_tools()).tools}
+            result = await client.call_tool(
+                "search_papers",
+                {"query": "transformer", "mode": "keyword", "limit": 1},
+            )
+        return tools, result
+
+    tools, result = asyncio.run(exercise())
+
+    assert tools["search_papers"].annotations.read_only_hint is True
+    assert tools["search_papers"].input_schema["properties"]["limit"]["maximum"] == 25
+    assert tools["search_papers"].input_schema["properties"]["mode"]["enum"] == [
+        "hybrid",
+        "keyword",
+        "semantic",
+    ]
+    # Same default as `pwc search --mode`.
+    assert (
+        tools["search_papers"].input_schema["properties"]["mode"]["default"] == "hybrid"
+    )
+    assert result.is_error is False
+    assert result.structured_content == {
+        "schema_version": "v1",
+        "items": [
+            {
+                "id": "755",
+                "arxiv_id": "1706.03762",
+                "title": "Attention Is All You Need",
+                "authors": ["Ashish Vaswani"],
+                "published": "2017-06-12",
+                "citation_count": 190_373,
+                "url": "https://arxiv.org/abs/1706.03762v7",
+                "has_official_implementation": True,
+                "code_repository_count": 595,
+            }
+        ],
+        "next_page": 2,
+        "note": None,
+        "available_at": None,
+        "data": PAPER_PAGE,
+    }
+    assert catalog.queries == [
+        (
+            ("search",),
+            {
+                "query": "transformer",
+                "mode": "keyword",
+                "page": 1,
+                "limit": 1,
+                "start_date": None,
+                "end_date": None,
+                "has_official_implementation": False,
+            },
+        )
+    ]
+
+
+def test_search_rejects_invalid_ranges_before_calling_the_catalog():
+    catalog = StubCatalog()
+    (result,) = _call(
+        catalog,
+        [
+            (
+                "search_papers",
+                {
+                    "query": "transformer",
+                    "published_after": "2026-08-31",
+                    "published_before": "2026-08-01",
+                },
+            )
+        ],
+    )
+
+    assert result.is_error is True
+    assert result.content[0].text == (
+        "Error executing tool search_papers: "
+        "published_after must be on or before published_before"
+    )
+    assert catalog.queries == []
+
+
+def test_catalog_failures_do_not_expose_or_log_user_queries(caplog):
+    secret_query = "private unreleased project heliotrope"
+
+    class FailingCatalog(StubCatalog):
+        def query(self, command, options):
+            raise ResponseError(f"API returned invalid JSON for {secret_query}")
+
+    with caplog.at_level(logging.INFO):
+        (result,) = _call(
+            FailingCatalog(), [("search_papers", {"query": secret_query})]
+        )
+
+    assert result.is_error is True
+    assert result.content[0].text == (
+        "Error executing tool search_papers: "
+        "upstream_error: the Papers With Code catalog request failed"
+    )
+    assert secret_query not in caplog.text
+
+
+def test_lookup_failures_return_the_cli_hint_without_logging_it(caplog):
+    class MissingCatalog(StubCatalog):
+        def query(self, command, options):
+            raise ResponseError(
+                "Task not found: language-modelling; closest results: Language Modeling"
+            )
+
+    class TransportCatalog(StubCatalog):
+        def query(self, command, options):
+            raise HTTPStatusError(404, "not found: language-modelling")
+
+    with caplog.at_level(logging.INFO):
+        (missing,) = _call(
+            MissingCatalog(), [("get_task", {"task": "language-modelling"})]
+        )
+        (transport,) = _call(
+            TransportCatalog(), [("get_task", {"task": "language-modelling"})]
+        )
+
+    assert missing.content[0].text == (
+        "Error executing tool get_task: "
+        "not_found: Task not found: language-modelling; closest results: Language Modeling"
+    )
+    assert transport.content[0].text == (
+        "Error executing tool get_task: not_found: the requested catalog record does not exist"
+    )
+    assert "language-modelling" not in caplog.text
+
+
+def test_cli_usage_errors_are_returned_verbatim():
+    class StrictCatalog(StubCatalog):
+        def query(self, command, options):
+            raise UsageError("unknown metric(s): latency; available metrics: Accuracy")
+
+    (result,) = _call(
+        StrictCatalog(),
+        [("get_benchmark", {"benchmark": "imagenet-1k", "sort_metric": "latency"})],
+    )
+
+    assert result.is_error is True
+    assert result.content[0].text == (
+        "Error executing tool get_benchmark: "
+        "unknown metric(s): latency; available metrics: Accuracy"
+    )
+
+
+def test_paper_info_and_reading_use_stable_schemas_and_opaque_continuation():
+    catalog = StubCatalog()
+
+    async def exercise():
+        async with Client(build_server(catalog, read_chunk_bytes=5)) as client:
+            info = await client.call_tool("get_paper_info", {"paper": "1706.03762"})
+            evaluated = await client.call_tool(
+                "get_paper_info",
+                {"paper": "1706.03762", "include_evaluations": True},
+            )
+            first = await client.call_tool("read_paper", {"paper": "1706.03762"})
+            second = await client.call_tool(
+                "read_paper",
+                {
+                    "paper": "1706.03762",
+                    "cursor": first.structured_content["next_cursor"],
+                },
+            )
+        return info, evaluated, first, second
+
+    info, evaluated, first, second = asyncio.run(exercise())
+
+    assert catalog.queries[0] == (
+        ("paper", "info"),
+        {"paper": "1706.03762", "include_resources": True, "include_evals": False},
+    )
+    paper = info.structured_content["paper"]
+    assert paper["title"] == "Attention Is All You Need"
+    assert paper["tasks"] == [
+        {"id": "6", "name": "Machine Translation", "slug": "machine-translation"}
+    ]
+    assert paper["repositories"][0]["is_official"] is True
+    assert paper["hf_models"] == []
+    assert paper["code_repository_count"] == 595
+    assert info.structured_content["evaluations"] is None
+    assert info.structured_content["data"] is None
+
+    assert catalog.queries[1][1]["include_evals"] is True
+    assert evaluated.structured_content["evaluation_count"] == 1
+    assert evaluated.structured_content["evaluations"] == [
+        {
+            "id": "40",
+            "benchmark": "WMT2014 English-German",
+            "task": "Machine Translation",
+            "model_name": "Transformer Big",
+            "harness": None,
+            "metrics": {"BLEU score": 28.4},
+            "best_metric": "BLEU score",
+            "best_rank": 3,
+            "is_open": True,
+            "num_parameters": 213_000_000,
+            "source_url": "https://example.test/result",
+        }
+    ]
+
+    assert first.structured_content["markdown"] == "abcde"
+    assert first.structured_content["truncated"] is True
+    assert first.structured_content["next_cursor"]
+    assert second.structured_content == {
+        "schema_version": "v1",
+        "paper": "1706.03762",
+        "markdown": "fgh",
+        "truncated": False,
+        "next_cursor": None,
+        "in_catalog": True,
+        "available_at": None,
+    }
+    assert catalog.resolve_calls == 1
+    assert catalog.read_calls == [(0, None, 5), (5, "a" * 64, 5)]
+
+
+def test_paper_evaluations_are_paginated_and_compact():
+    catalog = StubCatalog()
+    (result,) = _call(
+        catalog,
+        [("get_paper_evaluations", {"paper": "1706.03762", "limit": 5})],
+    )
+
+    assert catalog.options(("paper", "evaluations")) == {
+        "paper": "1706.03762",
+        "page": 1,
+        "page_size": 5,
+    }
+    assert result.structured_content["next_page"] == 2
+    assert result.structured_content["data"] is None
+    assert (
+        result.structured_content["evaluations"][0]["rank_scopes"][0]["task_name"]
+        == "Image Classification"
+    )
+
+
+def test_read_paper_rejects_invalid_continuation_as_an_expected_error():
+    (result,) = _call(
+        StubCatalog(),
+        [("read_paper", {"paper": "1706.03762", "cursor": "%%%private%%%"})],
+    )
+
+    assert result.is_error is True
+    assert result.content[0].text == (
+        "Error executing tool read_paper: invalid continuation cursor; pass the "
+        "next_cursor value from the previous read_paper result, or omit cursor to "
+        "start from the beginning"
+    )
+
+
+class AliasedStubCatalog(StubCatalog):
+    """Resolves the numeric catalog ID and the arXiv ID to the same paper."""
+
+    def resolve_paper(self, paper: str):
+        self.resolve_calls += 1
+        return {"1706.03762": "1706.03762", "755": "1706.03762", "1810.04805": "1810.04805"}[paper]
+
+
+def test_read_paper_continues_with_another_reference_to_the_same_paper():
+    # Agents start from the arXiv ID and continue with the numeric ID that
+    # list tools hand out; the cursor must follow the paper, not the spelling.
+    catalog = AliasedStubCatalog()
+
+    async def exercise():
+        async with Client(build_server(catalog, read_chunk_bytes=5)) as client:
+            first = await client.call_tool("read_paper", {"paper": "1706.03762"})
+            cursor = first.structured_content["next_cursor"]
+            same = await client.call_tool("read_paper", {"paper": "755", "cursor": cursor})
+            other = await client.call_tool("read_paper", {"paper": "1810.04805", "cursor": cursor})
+        return first, same, other
+
+    first, same, other = asyncio.run(exercise())
+
+    assert first.structured_content["markdown"] == "abcde"
+    assert same.is_error is False
+    assert same.structured_content["paper"] == "755"
+    assert same.structured_content["markdown"] == "fgh"
+    assert same.structured_content["next_cursor"] is None
+    assert other.is_error is True
+    assert other.content[0].text == (
+        "Error executing tool read_paper: continuation cursor belongs to a different "
+        "paper; omit cursor to start reading this paper from the beginning"
+    )
+    assert catalog.read_calls == [(0, None, 5), (5, "a" * 64, 5)]
+
+
+def test_paper_listing_related_work_and_lineage_are_composable():
+    catalog = StubCatalog()
+    listed, recent, trending, related, lineage = _call(
+        catalog,
+        [
+            (
+                "list_papers",
+                {
+                    "task": "machine-translation",
+                    "authors": ["Ashish Vaswani"],
+                    "limit": 1,
+                },
+            ),
+            ("list_recent_papers", {"limit": 3}),
+            ("list_trending_papers", {"max_age_days": 30, "min_velocity": 1.5}),
+            ("get_related_papers", {"paper": "1706.03762", "limit": 2}),
+            ("get_paper_lineage", {"paper": "1706.03762"}),
+        ],
+    )
+
+    assert catalog.options(("paper", "list")) == {
+        "search": None,
+        "task": "machine-translation",
+        "method": None,
+        "conference": None,
+        "framework": None,
+        "organization": None,
+        "author": ["Ashish Vaswani"],
+        "start_date": None,
+        "end_date": None,
+        "all_versions": False,
+        "order_by": "trending",
+        "order_dir": "desc",
+        "include_resources": False,
+        "has_official_implementation": False,
+        "page": 1,
+        "page_size": 1,
+    }
+    assert catalog.options(("paper", "recent")) == {"limit": 3}
+    assert catalog.options(("paper", "trending")) == {
+        "limit": 20,
+        "max_age_days": 30,
+        "min_velocity": 1.5,
+    }
+    assert catalog.options(("paper", "related")) == {"paper": "1706.03762", "limit": 2}
+    assert catalog.options(("paper", "lineage", "list")) == {"paper": "1706.03762"}
+    assert listed.structured_content["items"][0]["arxiv_id"] == "1706.03762"
+    assert recent.structured_content["next_page"] is None
+    assert recent.structured_content["items"][0]["id"] == "755"
+    assert recent.structured_content["data"] == [PAPER_ROW]
+    assert trending.structured_content["items"][0]["id"] == "755"
+    assert related.structured_content["items"][0]["id"] == "755"
+    assert lineage.structured_content["paper"]["reference"] == "1706.03762"
+    assert lineage.structured_content["successors"] == [
+        {"id": "900", "reference": "2001.00001", "title": "A Follow-up"}
+    ]
+
+
+def test_taxonomy_and_benchmark_tools_return_stable_catalog_entities():
+    catalog = StubCatalog()
+
+    async def exercise():
+        async with Client(build_server(catalog)) as client:
+            tool_names = {tool.name for tool in (await client.list_tools()).tools}
+            task = await client.call_tool("get_task", {"task": "image-classification"})
+            method = await client.call_tool("get_method", {"method": "transformer"})
+            benchmarks = await client.call_tool(
+                "list_benchmarks", {"task": "image-classification"}
+            )
+            benchmark = await client.call_tool(
+                "get_benchmark",
+                {
+                    "benchmark": "imagenet-1k",
+                    "limit": 5,
+                    "is_open": True,
+                    "max_parameters": "4B",
+                    "minimum_metrics": {"Accuracy": 80},
+                    "sort_metric": "Accuracy:desc",
+                },
+            )
+        return tool_names, task, method, benchmarks, benchmark
+
+    tool_names, task, method, benchmarks, benchmark = asyncio.run(exercise())
+
+    assert tool_names == set(TOOL_COMMANDS)
+    assert len(tool_names) == 21
+    assert catalog.options(("task",)) == {"name": "image-classification"}
+    assert catalog.options(("method",)) == {"name": "transformer"}
+    assert catalog.options(("benchmark", "list")) == {
+        "search": None,
+        "task": "image-classification",
+        "include_descendants": False,
+        "min_eval_count": None,
+        "is_open": None,
+        "group_by_area": False,
+        "area": None,
+        "benchmarks_per_task": 3,
+        "order_by": None,
+        "order_dir": "asc",
+        "page": 1,
+        "page_size": 25,
+    }
+    assert catalog.options(("benchmark",)) == {
+        "name": "imagenet-1k",
+        "page": 1,
+        "limit": 5,
+        "is_open": True,
+        "max_parameters": "4B",
+        "require_metrics": None,
+        "minimum_metrics": {"Accuracy": 80.0},
+        "maximum_metrics": None,
+        "sort_metric": "Accuracy:desc",
+        "pareto": None,
+    }
+    assert task.structured_content["task"]["area"] == {"id": "1", "name": "Vision"}
+    assert task.structured_content["task"]["benchmarks"][0]["slug"] == "imagenet-1k"
+    assert task.structured_content["data"] is None
+    assert method.structured_content["method"]["introduced_year"] == 2017
+    assert benchmarks.structured_content["items"][0]["slug"] == "imagenet-1k"
+    assert benchmark.structured_content["matched_count"] == 1
+    assert benchmark.structured_content["next_page"] == 2
+    evaluation = benchmark.structured_content["evaluations"][0]
+    assert evaluation["model_name"] == "ExampleNet"
+    assert evaluation["metrics"] == {"Accuracy": 90.1}
+    assert evaluation["rank_scopes"] == [
+        {
+            "task_id": None,
+            "task_name": "Image Classification",
+            "task_slug": None,
+            "rank": 1,
+        }
+    ]
+    assert benchmark.structured_content["metric_directions"] == {"Accuracy": "higher"}
+
+
+def test_grouped_listings_omit_pagination_and_flatten_benchmarks():
+    catalog = StubCatalog()
+    tasks, grouped_tasks, benchmarks = _call(
+        catalog,
+        [
+            ("list_tasks", {"area": "Vision", "level": 1}),
+            ("list_tasks", {"group_by_area": True}),
+            ("list_benchmarks", {"area": "Vision", "benchmarks_per_task": 2}),
+        ],
+    )
+
+    assert catalog.queries[0] == (
+        ("task", "list"),
+        {
+            "search": None,
+            "area": "Vision",
+            "level": 1,
+            "visible_only": False,
+            "group_by_area": False,
+            "order_by": "name",
+            "order_dir": "asc",
+            "page": 1,
+            "page_size": 25,
+        },
+    )
+    assert catalog.queries[1][1]["group_by_area"] is True
+    assert catalog.queries[1][1]["page_size"] is None
+    assert catalog.queries[2][1]["page_size"] is None
+    assert catalog.queries[2][1]["benchmarks_per_task"] == 2
+    assert tasks.structured_content == {
+        "schema_version": "v1",
+        "data": {"count": 1, "results": [TASK]},
+    }
+    assert grouped_tasks.structured_content["data"] == {"count": 1, "results": [TASK]}
+    assert benchmarks.structured_content["items"] == [
+        {
+            "id": "72",
+            "name": "ImageNet-1k",
+            "slug": "imagenet-1k",
+            "full_name": None,
+            "description": None,
+            "split": None,
+            "hf_url": None,
+            "paper_count": 124,
+        }
+    ]
+    assert benchmarks.structured_content["data"] == GROUPED_BENCHMARKS
+
+
+def test_new_catalog_tools_return_the_cli_json_document():
+    catalog = StubCatalog()
+    requests = [
+        ("list_methods", {"introduced_year": 2017, "order_by": "paper_count"}),
+        ("get_conference", {"conference": "CVPR 2025"}),
+        ("list_conferences", {"year": 2025}),
+        ("get_organization", {"organization": "NVIDIA"}),
+        ("list_organizations", {"featured_only": True}),
+        ("get_framework", {"framework": "vLLM"}),
+        ("list_frameworks", {"platform": "gpu"}),
+    ]
+    results = _call(catalog, requests)
+
+    for (name, _arguments), result in zip(requests, results):
+        assert result.is_error is False, name
+        assert result.structured_content == {
+            "schema_version": "v1",
+            "data": PAYLOADS[TOOL_COMMANDS[name]],
+        }
+    assert catalog.options(("method", "list")) == {
+        "search": None,
+        "area": None,
+        "introduced_year": 2017,
+        "order_by": "paper_count",
+        "order_dir": "asc",
+        "page": 1,
+        "page_size": 25,
+    }
+    assert catalog.options(("conference",)) == {"name": "CVPR 2025"}
+    assert catalog.options(("conference", "list")) == {"year": 2025}
+    assert catalog.options(("organization",)) == {"name": "NVIDIA"}
+    assert catalog.options(("organization", "list")) == {"featured_only": True}
+    assert catalog.options(("framework",)) == {"name": "vLLM"}
+    assert catalog.options(("framework", "list")) == {
+        "domain": None,
+        "category": None,
+        "platform": "gpu",
+    }
+
+
+def test_resources_expose_canonical_papers_tasks_and_benchmarks():
+    async def exercise():
+        async with Client(build_server(StubCatalog())) as client:
+            templates = {
+                template.uri_template
+                for template in (
+                    await client.list_resource_templates()
+                ).resource_templates
+            }
+            paper = await client.read_resource("pwc://papers/1706.03762")
+            markdown = await client.read_resource("pwc://papers/1706.03762/markdown")
+            task = await client.read_resource("pwc://tasks/image-classification")
+            benchmark = await client.read_resource("pwc://benchmarks/imagenet-1k")
+        return templates, paper, markdown, task, benchmark
+
+    templates, paper, markdown, task, benchmark = asyncio.run(exercise())
+
+    assert templates == {
+        "pwc://papers/{paper}",
+        "pwc://papers/{paper}/markdown",
+        "pwc://tasks/{task}",
+        "pwc://benchmarks/{benchmark}",
+    }
+    assert '"title":"Attention Is All You Need"' in paper.contents[0].text
+    assert markdown.contents[0].text == "abcdefgh"
+    assert '"slug":"image-classification"' in task.contents[0].text
+    assert '"slug":"imagenet-1k"' in benchmark.contents[0].text
+
+
+def test_upstream_validation_rate_limit_and_timeout_errors_are_actionable(caplog):
+    from pwc_cli.transport import TransportError
+    from pwc_mcp.server import catalog_error_message
+
+    class ErrorCatalog(StubCatalog):
+        def __init__(self, error):
+            super().__init__()
+            self.error = error
+
+        def query(self, command, options):
+            raise self.error
+
+    cases = {
+        HTTPStatusError(422, '{"detail":"page_size must be <= 100"}\n\x00'): (
+            'invalid_argument: {"detail":"page_size must be <= 100"}'
+        ),
+        HTTPStatusError(429, "slow down"): (
+            "rate_limited: the Papers With Code catalog is rate limiting; retry later"
+        ),
+        TransportError("API request timed out"): (
+            "upstream_timeout: the Papers With Code catalog timed out"
+        ),
+        ResponseError("Paper not found: 2308.10195"): (
+            "not_found: Paper not found: 2308.10195"
+        ),
+        ResponseError("Paper URL not supported: https://doi.org/x; only arXiv"): (
+            "not_found: Paper URL not supported: https://doi.org/x; only arXiv"
+        ),
+    }
+    for error, expected in cases.items():
+        (result,) = _call(ErrorCatalog(error), [("get_task", {"task": "x"})])
+        assert result.is_error is True
+        assert result.content[0].text == f"Error executing tool get_task: {expected}"
+
+    with caplog.at_level(logging.WARNING):
+        assert catalog_error_message(ResponseError("API returned invalid JSON")) == (
+            "upstream_error: the Papers With Code catalog request failed"
+        )
+    assert "pwc-mcp generic catalog error type=ResponseError" in caplog.text
+    assert "invalid JSON" not in caplog.text
+
+
+def test_list_benchmarks_falls_back_instead_of_rejecting_argument_combinations():
+    catalog = StubCatalog()
+    trending_search, area_with_search, area_only = _call(
+        catalog,
+        [
+            (
+                "list_benchmarks",
+                {"search": "COCO", "order_by": "trending", "order_direction": "desc"},
+            ),
+            ("list_benchmarks", {"area": "Vision", "search": "HDR", "limit": 10}),
+            ("list_benchmarks", {"area": "Vision", "limit": 10}),
+        ],
+    )
+
+    # order_by=trending needs a task; the CLI would raise a usage error.
+    assert catalog.queries[0][1]["order_by"] is None
+    assert catalog.queries[0][1]["search"] == "COCO"
+    assert trending_search.is_error is False
+    assert "Note: order_by=trending needs task; ordered by name instead." in (
+        trending_search.content[0].text
+    )
+    assert trending_search.structured_content["items"][0]["slug"] == "imagenet-1k"
+
+    # area cannot be combined with flat filters; the filters win.
+    assert catalog.queries[1][1]["area"] is None
+    assert catalog.queries[1][1]["search"] == "HDR"
+    assert catalog.queries[1][1]["page_size"] == 10
+    assert "area cannot be combined with filters" in area_with_search.content[0].text
+
+    # A bare limit does not conflict with grouping: the grouped listing ignores it.
+    assert catalog.queries[2][1]["area"] == "Vision"
+    assert catalog.queries[2][1]["page_size"] is None
+    assert "Note:" not in area_only.content[0].text
+    assert area_only.content[0].text == "Found 1 benchmarks."
+
+
+def test_read_paper_names_an_identity_mismatch_instead_of_a_generic_failure():
+    class DriftingCatalog(StubCatalog):
+        def read_paper_chunk(self, paper, **kwargs):
+            chunk = super().read_paper_chunk(paper, **kwargs)
+            return PaperMarkdownChunk(
+                paper="9999.99999",
+                source=chunk.source,
+                markdown=chunk.markdown,
+                content_version=chunk.content_version,
+                next_offset=chunk.next_offset,
+            )
+
+    (result,) = _call(DriftingCatalog(), [("read_paper", {"paper": "1706.03762"})])
+
+    assert result.is_error is True
+    assert result.content[0].text == (
+        "Error executing tool read_paper: paper changed; restart reading from the beginning"
+    )
+
+
+def test_paper_detail_includes_x_threads_only_with_resources():
+    item = {
+        **PAPER_INFO,
+        "x_threads": [
+            {
+                "url": "https://x.com/author/status/123",
+                "author_name": "Ada Author",
+                "author_handle": "author",
+                "text": "Introducing our paper",
+            },
+            {"author_name": "No URL"},
+        ],
+    }
+
+    threads = paper_detail(item, include_resources=True, repo_limit=5).x_threads
+    assert [thread.model_dump() for thread in threads] == [
+        {
+            "url": "https://x.com/author/status/123",
+            "author": "Ada Author",
+            "handle": "author",
+        }
+    ]
+    assert paper_detail(item, include_resources=False, repo_limit=5).x_threads == []
+
+
+PUBLIC_PAPER = {
+    "in_catalog": False,
+    "catalog_id": None,
+    "catalog_url": None,
+    "note": "Not indexed on Papers With Code.",
+    "id": "2309.06920",
+    "arxiv_id": "2309.06920",
+    "doi": None,
+    "title": "A Paper Outside The Catalog",
+    "authors": ["Ada Lovelace"],
+    "abstract": "An abstract.",
+    "published": "2023-09-13",
+    "url": "https://arxiv.org/abs/2309.06920",
+    "pdf_url": "https://arxiv.org/pdf/2309.06920",
+    "hf_url": "https://huggingface.co/papers/2309.06920",
+    "repositories": ["https://github.com/example/outside"],
+    "project_pages": [],
+    "metadata_source": "huggingface",
+    "available_at": [
+        {"label": "arXiv", "url": "https://arxiv.org/abs/2309.06920", "kind": "abstract"},
+        {"label": "PDF", "url": "https://arxiv.org/pdf/2309.06920", "kind": "pdf"},
+        {"label": "Code", "url": "https://github.com/example/outside", "kind": "code"},
+    ],
+}
+
+
+class OutsideCatalog(StubCatalog):
+    """Holds only 1706.03762; knows public metadata for other references."""
+
+    def __init__(self, public=None):
+        super().__init__()
+        self.public = {"2309.06920": PUBLIC_PAPER} if public is None else public
+        self.public_calls = []
+
+    def resolve_paper(self, paper):
+        self.resolve_calls += 1
+        if paper in {"1706.03762", "Attention Is All You Need"}:
+            return "1706.03762"
+        if paper[0].isdigit() and "/" not in paper:
+            return paper
+        raise ResponseError(f"Paper title not found: {paper}")
+
+    def read_paper_chunk(self, paper, **options):
+        if paper != "1706.03762":
+            raise ResponseError(f"Paper not found: {paper}")
+        return super().read_paper_chunk(paper, **options)
+
+    def query(self, command, options):
+        paper = options.get("paper")
+        if paper is not None and self.resolve_paper(paper) != "1706.03762":
+            self.queries.append((tuple(command), dict(options)))
+            raise HTTPStatusError(404, "Paper not found")
+        return super().query(command, options)
+
+    def public_paper(self, reference):
+        self.public_calls.append(reference)
+        return self.public.get(reference, PublicPaperMiss("identifier"))
+
+
+def test_paper_tools_fall_back_to_public_metadata_outside_the_catalog():
+    catalog = OutsideCatalog()
+    info, read, related = _call(
+        catalog,
+        [
+            ("get_paper_info", {"paper": "2309.06920"}),
+            ("read_paper", {"paper": "2309.06920"}),
+            ("get_related_papers", {"paper": "2309.06920", "limit": 3}),
+        ],
+    )
+
+    assert info.is_error is False
+    assert info.structured_content["in_catalog"] is False
+    note = info.structured_content["note"]
+    assert "not indexed on Papers With Code" in note
+    assert "no Papers With Code page" in note
+    assert "public Hugging Face Papers records" in note
+    assert "arXiv: https://arxiv.org/abs/2309.06920" in note
+    assert "not indexed on Papers With Code" in info.content[0].text
+    assert info.structured_content["available_at"] == PUBLIC_PAPER["available_at"]
+    paper = info.structured_content["paper"]
+    assert paper["title"] == "A Paper Outside The Catalog"
+    assert paper["authors"] == ["Ada Lovelace"]
+    assert paper["abstract"] == "An abstract."
+    assert paper["published"] == "2023-09-13"
+    assert paper["url"] == "https://arxiv.org/abs/2309.06920"
+    assert paper["repositories"] == [
+        {"url": "https://github.com/example/outside", "is_official": False}
+    ]
+    assert paper["tasks"] == [] and paper["methods"] == []
+
+    assert read.is_error is False
+    assert read.structured_content["in_catalog"] is False
+    assert read.structured_content["truncated"] is False
+    assert read.structured_content["next_cursor"] is None
+    assert read.structured_content["available_at"] == PUBLIC_PAPER["available_at"]
+    markdown = read.structured_content["markdown"]
+    assert markdown.startswith("# A Paper Outside The Catalog\n")
+    assert "not indexed on Papers With Code" in markdown
+    assert "## Available at\n\n- [arXiv](https://arxiv.org/abs/2309.06920)" in markdown
+    assert "- [Code](https://github.com/example/outside)" in markdown
+    assert markdown.endswith("An abstract.\n")
+
+    assert related.is_error is False
+    assert "not indexed on Papers With Code" in related.structured_content["note"]
+    assert related.structured_content["available_at"] == PUBLIC_PAPER["available_at"]
+    assert catalog.options(("search",)) == {
+        "query": "A Paper Outside The Catalog",
+        "mode": "hybrid",
+        "page": 1,
+        "limit": 3,
+    }
+
+
+def test_paper_misses_without_public_metadata_keep_an_explicit_not_found():
+    (info,) = _call(OutsideCatalog(public={}), [("get_paper_info", {"paper": "2108.05103"})])
+
+    assert info.is_error is True
+    assert info.content[0].text == (
+        "Error executing tool get_paper_info: not_found: the requested catalog record "
+        "does not exist; it is not indexed on Papers With Code and no public Hugging "
+        "Face Papers, arXiv, or Crossref record matched it"
+    )
+
+
+def test_a_reference_the_public_metadata_api_finds_in_the_catalog_returns_the_catalog_paper():
+    doi = "10.48550/arXiv.1706.03762"
+    record = {**PUBLIC_PAPER, "in_catalog": True, "catalog_id": "755",
+              "id": doi, "arxiv_id": "1706.03762", "doi": doi,
+              "title": "Attention Is All You Need",
+              "metadata_source": "paperswithcode"}
+    catalog = OutsideCatalog(public={doi: record})
+    info, read = _call(
+        catalog,
+        [("get_paper_info", {"paper": doi}), ("read_paper", {"paper": doi})],
+    )
+
+    assert info.structured_content["in_catalog"] is True
+    assert info.structured_content["paper"]["arxiv_id"] == "1706.03762"
+    assert read.structured_content["in_catalog"] is True
+    assert read.structured_content["paper"] == "1706.03762"
+    assert read.structured_content["markdown"] == "abcdefgh"
+
+
+def test_a_cataloged_record_that_cannot_be_read_keeps_the_original_error():
+    # The API says the reference is cataloged, but the catalog ID still misses:
+    # never present a cataloged paper as outside the catalog.
+    doi = "10.5555/gone"
+    record = {**PUBLIC_PAPER, "in_catalog": True, "arxiv_id": "2108.05103",
+              "catalog_id": "99"}
+    (info, read) = _call(
+        OutsideCatalog(public={doi: record}),
+        [("get_paper_info", {"paper": doi}), ("read_paper", {"paper": doi})],
+    )
+
+    assert info.is_error is True and "not_found" in info.content[0].text
+    assert read.is_error is True
+
+
+def test_read_paper_treats_a_placeholder_cursor_as_the_beginning():
+    # Production chat sent cursor="next" before any read (28 failures a week,
+    # then identical retries).
+    catalog = StubCatalog()
+    next_read, start_read = _call(
+        catalog,
+        [
+            ("read_paper", {"paper": "1706.03762", "cursor": "next"}),
+            ("read_paper", {"paper": "1706.03762", "cursor": " Start "}),
+        ],
+    )
+
+    assert next_read.is_error is False
+    assert next_read.structured_content["markdown"] == "abcdefgh"
+    assert start_read.is_error is False
+    assert catalog.read_calls == [(0, None, 65_536), (0, None, 65_536)]
+
+
+def test_get_benchmark_returns_the_leaderboard_when_a_metric_is_unknown():
+    class MetricCatalog(StubCatalog):
+        def query(self, command, options):
+            if options.get("sort_metric") or options.get("require_metrics"):
+                self.queries.append((tuple(command), dict(options)))
+                raise UsageError(
+                    "unknown metric(s): overall; available metrics: Accuracy, F1"
+                )
+            return super().query(command, options)
+
+    catalog = MetricCatalog()
+    (result,) = _call(
+        catalog,
+        [("get_benchmark", {"benchmark": "imagenet-1k", "sort_metric": "overall"})],
+    )
+
+    assert result.is_error is False
+    assert result.structured_content["metric_note"] == (
+        "unknown metric(s): overall; available metrics: Accuracy, F1; returned the "
+        "leaderboard without metric filters or metric sorting"
+    )
+    assert result.structured_content["evaluations"][0]["model_name"] == "ExampleNet"
+    assert "available metrics: Accuracy, F1" in result.content[0].text
+    retried = catalog.queries[-1][1]
+    assert "sort_metric" not in retried and "require_metrics" not in retried
+
+
+@pytest.mark.parametrize(
+    ("reason", "wording"),
+    [
+        ("title", "no arXiv or Crossref paper has exactly this title"),
+        ("unsupported", "it was not looked up publicly"),
+        ("unavailable", "the public Hugging Face Papers, arXiv, and Crossref lookup is"),
+    ],
+)
+def test_paper_misses_say_what_the_public_lookup_tried(reason, wording):
+    title = "A Classic Paper Title"
+    catalog = OutsideCatalog(public={title: PublicPaperMiss(reason)})
+
+    (info,) = _call(catalog, [("get_paper_info", {"paper": title})])
+
+    assert info.is_error is True
+    text = info.content[0].text
+    assert "it is not indexed on Papers With Code and " + wording in text
+    assert "no public Hugging Face Papers" not in text
+
+
+def test_a_title_resolved_by_its_name_says_the_full_title_differs():
+    requested = "GlobalTrack: A Simple and Universal Tracker with Global Features"
+    record = {
+        **PUBLIC_PAPER,
+        "title": "GlobalTrack: A Simple and Strong Baseline for Long-term Tracking",
+        "requested_title": requested,
+    }
+    exact = {**PUBLIC_PAPER, "title": "Same Title.", "requested_title": "same title"}
+    catalog = OutsideCatalog(public={requested: record, "same title": exact})
+
+    renamed, same = _call(
+        catalog,
+        [
+            ("get_paper_info", {"paper": requested}),
+            ("get_paper_info", {"paper": "same title"}),
+        ],
+    )
+
+    assert renamed.structured_content["in_catalog"] is False
+    assert renamed.structured_content["note"].startswith(
+        f'No paper is titled exactly "{requested}"; this is the paper with the '
+        'same name, titled "GlobalTrack: A Simple and Strong Baseline'
+    )
+    assert same.structured_content["note"].startswith("This paper is not indexed")
+
+
+@pytest.mark.parametrize(
+    ("arguments", "expected"),
+    [
+        ({"minimum_evaluations": 0}, None),
+        ({"minimum_evaluations": -3}, None),
+        ({"minimum_evaluations": 2}, 2),
+        ({"minimum_evaluations": 0, "group_by_area": True}, 0),
+    ],
+)
+def test_list_benchmarks_never_sends_a_minimum_the_api_rejects(arguments, expected):
+    catalog = StubCatalog()
+
+    (result,) = _call(catalog, [("list_benchmarks", arguments)])
+
+    assert result.is_error is False
+    assert catalog.queries[0][1]["min_eval_count"] == expected

mcp_server/tests/test_skill.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pwc_mcp.server import TOOL_COMMANDS
+
+SKILL = Path(__file__).parents[1] / "SKILL.md"
+EXPECTED_TOOLS = set(TOOL_COMMANDS)
+
+
+def test_mcp_skill_has_valid_agent_skills_frontmatter() -> None:
+    text = SKILL.read_text(encoding="utf-8")
+    assert text.startswith("---\n")
+    frontmatter = text.split("---\n", 2)[1]
+
+    name = re.search(r"^name: ([a-z0-9-]+)$", frontmatter, re.MULTILINE)
+    description = re.search(r'^description: "(.+)"$', frontmatter, re.MULTILINE)
+    compatibility = re.search(r'^compatibility: "(.+)"$', frontmatter, re.MULTILINE)
+
+    assert name is not None and name.group(1) == "pwc-mcp"
+    assert description is not None and 1 <= len(description.group(1)) <= 1024
+    assert compatibility is not None and len(compatibility.group(1)) <= 500
+
+
+def test_mcp_skill_documents_every_public_tool_without_inventing_tools() -> None:
+    text = SKILL.read_text(encoding="utf-8")
+    tools_section = text.split("## Tools\n", 1)[1].split("## Research workflow", 1)[0]
+    documented = set(re.findall(r"^- `([a-z_]+)\(", tools_section, re.MULTILINE))
+
+    assert documented == EXPECTED_TOOLS
+    assert re.search(r"Do not invent equivalent\s+tools", tools_section)
+
+
+def test_mcp_skill_explains_paper_continuation_contract() -> None:
+    text = SKILL.read_text(encoding="utf-8")
+
+    assert "next_cursor" in text
+    assert "Treat the cursor as opaque" in text
+    assert "same `paper`" in text
+    assert "within one hour" in text

standalone_cli/README.md

@@ -0,0 +1,179 @@
+# pwc CLI
+
+A lightweight, read-only client for the public Papers With Code catalog API.
+Public reads are anonymous: no login or token is required.
+
+```bash
+uv tool install ./standalone_cli
+pwc search "small vision language models" --limit 10
+pwc paper info 2501.01234
+pwc paper info 2501.01234 --include-resources
+pwc paper info 2501.01234 --include-evals
+pwc paper info "Attention Is All You Need"
+pwc paper read 2501.01234
+pwc task --name "scene-text-recognition"
+pwc task list --area Vision
+pwc task list --group-by-area
+pwc method --name Transformer
+pwc method list --area Audio
+pwc conference --name "CVPR 2025"
+pwc conference list --year 2025
+pwc organization --name NVIDIA
+pwc organization list --featured-only
+pwc framework --name vLLM
+pwc framework list --platform gpu
+pwc benchmark list
+pwc skills add
+```
+
+Every `PAPER` argument accepts an arXiv ID, numeric external-paper ID, or quoted
+exact title. Title matching is case-insensitive and rejects ambiguity.
+When `pwc paper info` or `pwc paper read` names a paper Papers With Code has not
+indexed, stderr shows "Not indexed on Papers With Code — available at:" with its
+public links (arXiv, Hugging Face Papers, DOI, code) and metadata from the
+`papers/{reference}/public-metadata` API. Stdout and the not-found exit status
+are unchanged; an arXiv or Hugging Face URL the API maps to a catalog paper is
+read from the catalog.
+
+`pwc paper info PAPER --include-evals` fetches every evaluation associated with
+the resolved paper. Human-readable output adds an Evaluations Markdown table;
+`--json` adds an `evaluations` object containing `count` and `results`.
+Normal paper-info output includes the names of tagged organizations when present.
+
+Task lists and benchmark lists render grouped Markdown in a terminal. Use
+`--flat` for paginated tables or `--group-by-area` to force Markdown when
+piping. Task, search, pagination, ordering, and open-model filters take
+precedence over `--group-by-area` and select task-scoped flat output. Grouped
+benchmarks include their name, full name when distinct, slug, and ID.
+Task-scoped benchmark lists also include the slug and ID alongside the best
+model, paper, and code repository, using aligned columns even when output is
+captured by an agent or another process. Inspect one with
+`pwc benchmark --name IDENTIFIER`; either identifier is accepted. Benchmark
+details use an aligned table in a terminal and Markdown when piped or captured.
+Other list and search output uses aligned columns in a terminal and lossless
+TSV when captured.
+
+Paper discovery commands accept `--implementation-coverage` to add
+`official_implementation` and `code_repositories` columns. JSON and
+`pwc paper info` always include those fields. The boolean reports whether the
+catalog links an official repository to any version of the paper; `false` does
+not prove that no official code exists elsewhere. `pwc search` and
+`pwc paper list` accept `--has-official-implementation` and fail closed unless
+the API confirms the filter.
+
+Task lists report each task's direct paper, benchmark, and evaluation counts in
+both grouped and flat output.
+
+`pwc task --name NAME` accepts an exact task name, slug, or ID and renders the
+task-page details in CLI form: area, description, hierarchy, research trends,
+recommended frameworks, sister tasks, subtasks, common methods, benchmarks,
+and trending papers. Direct benchmarks follow the ranking returned by the
+task benchmark-trends API; the CLI does not calculate or re-sort trend scores.
+Add `--json` for the complete structured payload.
+
+Methods, conferences, organizations, and frameworks share the same detail
+shape as tasks: pass an exact name, slug, or ID to `--name`. Their `list`
+subcommands retain entity-specific filters such as method area, conference
+year, featured organizations, and framework domain, category, or platform.
+`pwc paper list` accepts exact `--task`, `--method`, `--conference`,
+`--framework`, and `--organization` filters. Repeat `--author` with exact
+normalized names, numeric IDs, or `@HF_USERNAME` references to require every
+listed co-author. Combine these filters to require every selected identity,
+tag, or catalog association. The CLI fails closed if the selected API does not
+confirm that it applied every requested catalog filter.
+Publication date ranges use inclusive `--start-date YYYY-MM-DD` and
+`--end-date YYYY-MM-DD` bounds; the start date cannot be later than the end date.
+
+For example, find an author's papers on a stated topic in newest-first order:
+
+```bash
+pwc paper list --author "Kaiming He" --search drift \
+  --order-by date_published --order-dir desc
+```
+
+Leaderboard inspection supports numeric multi-metric selection:
+
+```bash
+pwc benchmark --name coco-val2017 --require-metrics mAP,FPS
+pwc benchmark --name coco-val2017 --min FPS=60 --sort mAP:desc
+pwc benchmark --name coco-val2017 --pareto mAP:higher,FPS:higher
+pwc benchmark --name wikitext-103 --is-open true --max-parameters 3B
+```
+
+`--min` and `--max` are repeatable. Metric names are case-insensitive. Metric
+selection scans the bounded leaderboard before applying `--limit`; it fails
+explicitly rather than returning an incomplete selection if a leaderboard
+exceeds the 1,000-row scan ceiling.
+
+`--max-parameters SIZE` keeps models at or below an inclusive parameter limit.
+SIZE accepts case-insensitive decimal suffixes such as `500M`, `1.5B`, and
+`3B`, plus raw integers. Parameter-constrained results exclude models whose
+parameter count is unknown or inconsistent across metric rows and fail closed
+against APIs that cannot confirm support. Human-readable leaderboard output
+includes a Parameters column; JSON retains the exact `num_parameters` integer.
+
+`pipx install ./standalone_cli` is also supported. `PWC_API_URL` selects a
+compatible versioned API origin; it defaults to
+`https://paperswithcode.co/api/v1`. Run `pwc --help` for the complete read-only
+command tree. The stable exit codes are 0 (success), 2 (usage), 3 (network or
+server failure), and 4 (invalid response).
+
+Install the version-matched Skill for coding agents with `pwc skills add`.
+Add `--global` to use `~/.agents/skills`, `--claude` to also link it for Claude
+Code, or `--dest PATH` for another harness.
+
+
+## Edit a paper with your agent
+
+Requires a server with the paper-edit API enabled. Sign in using the browser
+link and confirm the paper and code. This grants one hour of write access to
+that paper; each batch publishes immediately under your HF username.
+
+```bash
+pwc auth login --paper 123       # --no-browser for remote machines
+pwc paper edit export 123 --output edits.json
+# Add explicit operations to edits.json; current is reference material.
+pwc paper edit preview 123 --file edits.json
+pwc paper edit submit 123 --file edits.json
+pwc auth status --paper 123
+pwc auth logout --paper 123
+```
+
+For example, add the following to the exported `operations` array, substituting
+real existing task/dataset/metric identifiers. A metrics dictionary lets you
+submit multiple scores without repeating model and benchmark details:
+
+```json
+{
+  "section": "evaluations",
+  "payload": {
+    "task_id": 1,
+    "dataset_id": 2,
+    "model_name": "Example model",
+    "methodology": "Test split, zero-shot; Table 3",
+    "metrics": {"Accuracy": 90.5, "F1": 88.1},
+    "source_url": "https://arxiv.org/abs/2601.00001"
+  }
+}
+```
+
+Add `evaluation_id` alongside `section` to correct a row. Other supported
+sections are tasks, methods, repositories, project_pages, hf_artifacts,
+x_threads, and source_url. `x_threads` takes `{"x_threads": [post URLs]}` in
+display order (at most 10); link only posts in which the paper's authors or
+their organization introduce the paper. Section replacements must retain unrelated entries. Evaluation
+updates preserve omitted fields. Existing benchmark/metric definitions are
+required; evaluation deletion and rank overrides are excluded.
+
+Batches contain at most 50 operations and 1 MiB. Invalid or stale batches write
+nothing. Retry uncertain network results with the exact same document and
+idempotency key. For a stale revision, export again and reconcile before retrying.
+Accounts share a 20-distinct-paper daily limit (UTC) and 30-publication-per-minute
+limit across the website and CLI; admins are exempt. `pwc skills add --force`
+installs the detailed agent workflow.
+
+Credentials are stored in mode-0600 files inside the mode-0700 directory
+`~/.config/pwc/edit-credentials`, keyed by API base URL and paper. Never copy
+these files into prompts or repositories. `PWC_API_URL` selects the target API;
+editing requires HTTPS, except on loopback development servers, and refuses
+redirects. Public read commands never load edit credentials.

standalone_cli/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: pwc-cli
+description: "Papers With Code CLI (`pwc`) for searching and reading AI/ML papers, discovering recent and trending research, finding related work and paper lineage, browsing tasks, methods, conferences, organizations, frameworks, and benchmark leaderboards, and submitting authenticated paper edits through the public Papers With Code catalog. Use whenever the user asks to find papers, survey literature, compare research, inspect an arXiv paper, explore AI/ML taxonomy or conferences, discover benchmarks or state-of-the-art models, or mentions Papers With Code, `pwc`, or `pwc-cli`."
+---
+
+Generated with `pwc v0.4.6`. Run `pwc skills add --force` to regenerate.
+
+Research commands query the public [Papers With Code](https://paperswithcode.co) catalog anonymously.
+Paper editing requires explicit browser authorization through `pwc auth login --paper PAPER`.
+Run `pwc --help` or a nested `--help` command when the live parser and this
+skill disagree; the parser is authoritative.
+
+Use compact output for reading and discovery. Add `--json` for programmatic
+filtering, joining, or schema-dependent processing.
+
+When the user identifies an author, prefer repeatable structured
+`pwc paper list --author AUTHOR` filters. Add `--search TEXT` for stated topic
+terms and explicit `--order-by date_published --order-dir desc` for newest or
+recent work. Author references accept an exact normalized name, numeric ID, or
+`@HF_USERNAME`; repeated authors use AND semantics.
+
+Publication date ranges are inclusive: use `--start-date YYYY-MM-DD` and
+`--end-date YYYY-MM-DD` with `pwc search` or `pwc paper list`; the start date
+must not be later than `--end-date`. The combined flags are
+`--start-date YYYY-MM-DD --end-date YYYY-MM-DD`.
+
+Paper discovery commands accept `--implementation-coverage` to add official
+implementation status and total linked repository count columns. JSON and
+`pwc paper info` always include both fields. Use
+`--has-official-implementation` with `pwc search` or `pwc paper list` to require
+a catalog-linked official repository; these filters fail closed if unconfirmed.
+
+Use `pwc benchmark --name NAME --max-parameters SIZE` to keep models at or
+below an inclusive parameter limit. SIZE accepts values such as `500M`, `1.5B`,
+`3B`, and raw integers. Models without one consistent parameter count are
+excluded from constrained results.
+
+`PAPER` accepts a modern or legacy arXiv ID, a numeric external-paper ID, or an
+exact paper title. Quote titles containing spaces. Title matching is
+case-insensitive but exact; ambiguous titles fail with their matching IDs.
+When `pwc paper info` or `pwc paper read` names a paper Papers With Code has
+not indexed, stderr shows "Not indexed on Papers With Code — available at:"
+with public links and metadata before the usual not-found error; cite those
+links, not a Papers With Code page.
+
+## Commands
+
+- `pwc search QUERY [--limit LIMIT] [--page PAGE] [--mode hybrid|keyword|semantic] [--start-date START_DATE] [--end-date END_DATE] [--has-official-implementation] [--implementation-coverage] [--json]` — search papers.
+- `pwc paper info PAPER [--include-resources] [--include-evals] [--json]` — show paper metadata including abstract.
+- `pwc paper evaluations PAPER [--page PAGE] [--page-size PAGE_SIZE] [--json]` — list one paper's benchmark evaluations.
+- `pwc paper read PAPER [--json]` — print stored paper Markdown.
+- `pwc paper list [--page PAGE] [--page-size PAGE_SIZE] [--search SEARCH] [--start-date START_DATE] [--end-date END_DATE] [--task TASK] [--method METHOD] [--conference CONFERENCE] [--framework FRAMEWORK] [--organization ORGANIZATION] [--author AUTHOR] [--all-versions] [--order-by trending|date_published|citation_count] [--order-dir asc|desc] [--include-resources] [--has-official-implementation] [--implementation-coverage] [--json]` — list and filter papers.
+- `pwc paper recent [--limit LIMIT] [--implementation-coverage] [--json]` — list recent papers.
+- `pwc paper trending [--limit LIMIT] [--max-age-days MAX_AGE_DAYS] [--min-velocity MIN_VELOCITY] [--implementation-coverage] [--json]` — list trending papers.
+- `pwc paper related PAPER [--limit LIMIT] [--implementation-coverage] [--json]` — list related papers.
+- `pwc paper lineage list PAPER [--json]` — list predecessors and successors.
+- `pwc paper edit export PAPER [--output OUTPUT]`.
+- `pwc paper edit preview PAPER [--file FILE]`.
+- `pwc paper edit submit PAPER [--file FILE]`.
+- `pwc task [--name NAME] [--json]` — inspect or list research tasks.
+- `pwc task list [--page PAGE] [--page-size PAGE_SIZE] [--search SEARCH] [--group-by-area] [--flat] [--area AREA] [--level LEVEL] [--visible-only] [--order-by name|created_at|level|paper_count] [--order-dir asc|desc] [--json]` — list and filter research tasks.
+- `pwc method [--name NAME] [--json]` — inspect or list research methods.
+- `pwc method list [--page PAGE] [--page-size PAGE_SIZE] [--search SEARCH] [--area AREA] [--introduced-year INTRODUCED_YEAR] [--order-by name|full_name|introduced_year|created_at|paper_count] [--order-dir asc|desc] [--json]` — list and filter research methods.
+- `pwc conference [--name NAME] [--json]` — inspect or list conferences.
+- `pwc conference list [--year YEAR] [--json]` — list conferences with imported papers.
+- `pwc organization [--name NAME] [--json]` — inspect or list research organizations.
+- `pwc organization list [--featured-only] [--json]` — list research organizations.
+- `pwc framework [--name NAME] [--json]` — inspect or list research frameworks.
+- `pwc framework list [--domain DOMAIN] [--category CATEGORY] [--platform PLATFORM] [--json]` — list research frameworks.
+- `pwc benchmark [--name NAME] [--limit LIMIT] [--page PAGE] [--is-open true|false] [--max-parameters SIZE] [--require-metrics METRIC[,METRIC]] [--min METRIC=VALUE] [--max METRIC=VALUE] [--sort METRIC[:ASC|DESC]] [--pareto METRIC:HIGHER,METRIC:LOWER] [--json]` — inspect benchmarks.
+- `pwc benchmark list [--page PAGE] [--page-size PAGE_SIZE] [--search SEARCH] [--task TASK] [--group-by-area] [--flat] [--area AREA] [--benchmarks-per-task BENCHMARKS_PER_TASK] [--include-descendants] [--min-eval-count MIN_EVAL_COUNT] [--is-open true|false] [--order-by trending|name|full_name|created_at|paper_count] [--order-dir asc|desc] [--json]` — list and filter benchmarks.
+- `pwc skills add [--global] [--claude] [--dest DEST] [--force]` — install the version-matched pwc CLI Skill.
+- `pwc version` — show CLI and API contract versions.
+- `pwc auth login [--paper PAPER] [--no-browser]`.
+- `pwc auth status [--paper PAPER]`.
+- `pwc auth logout [--paper PAPER]`.
+
+## Research workflow
+
+1. Use `pwc benchmark list --task TASK` to discover active benchmarks, then
+   `pwc benchmark --name NAME` to inspect a leaderboard. Add
+   `--max-parameters SIZE` when model size is part of the request.
+2. Use `pwc paper info` to inspect promising results. Add
+   `--include-resources` when repositories, project pages, or Hugging Face
+   artifacts matter.
+3. Use exact `pwc paper list --author`, `--task`, `--method`, `--conference`,
+   `--framework`, and `--organization` filters for known identities or catalog
+   associations. Combine them to require every association; do not substitute
+   a keyword search. Add `--search` for title or abstract topic terms.
+4. Use `pwc search` for broader discovery, then `pwc paper read` for primary
+   evidence.
+5. Expand the literature with `pwc paper related` and use
+   `pwc paper lineage list` when model or method ancestry matters.
+6. Preserve paper titles, identifiers, and URLs so claims remain traceable.
+
+## Output and limits
+
+- Interactive output is optimized for people. Benchmark lists remain aligned
+  when captured; other captured list output uses lossless TSV. Add `--json` for
+  structured agent or script consumption.
+- Stable exit codes are `0` success, `2` invalid usage, `3` network/server
+  failure, and `4` invalid API response.
+- `PWC_API_URL` may select another compatible v1 endpoint. The default is
+  `https://paperswithcode.co/api/v1`.
+- Catalog-filtered paper lists fail closed unless the server confirms every
+  requested filter; never treat results from an older server as filtered.
+- Parameter-filtered benchmark details fail closed unless the server confirms
+  parameter-filter support and every returned model satisfies the limit.
+
+The research commands contain no authentication, catalog mutation, ingestion,
+publication, image, embedding, CRON, or infrastructure-maintenance operations.
+
+
+## Editing one paper
+
+Use this workflow only when the user requests edits. Research commands remain anonymous.
+
+1. Run `pwc auth login --paper PAPER`. Give the user the browser link and code;
+   they sign in with Hugging Face and authorize that paper for one hour. Use
+   `--no-browser` on a remote machine. Never extract, print, or copy credentials.
+2. Run `pwc paper edit export PAPER --output edits.json` (the output must not
+   already exist). It includes paper_id, version, idempotency_key, empty operations,
+   and current reference data. Change operations, not current. Preserve the
+   exported version and retry key. Documents may contain at most 50 operations
+   and 1 MiB of JSON.
+3. Add operations of the form `{"section":"tasks","payload":{"task_ids":[1,2]}}`.
+   A section operation explicitly replaces that section; preserve unrelated links
+   and tags. Omitted sections stay unchanged. Allowed sections and payload keys:
+   tasks/task_ids, methods/method_ids, repositories/repositories,
+   project_pages/project_pages, hf_artifacts/hf_models+hf_datasets+hf_spaces,
+   x_threads/x_threads, source_url/source_url (external papers only), and
+   evaluations. Repository/project-page entries contain url and is_official.
+   x_threads is a list of x.com or twitter.com post URLs in display order (at
+   most 10). Link only posts in which the paper's authors or their organization
+   introduce the paper, never outside accounts; the server captures each post's
+   preview and rejects deleted or protected posts.
+4. For evaluations, an operation without evaluation_id creates a row. Include
+   task_id, dataset_id, metrics (a dictionary of existing metric names to scores),
+   model_name, and the evaluation setup where available. One row can contain
+   multiple metrics. Add evaluation_id to correct an existing row on this paper;
+   omitted update fields stay unchanged. Use source_url and methodology to cite
+   precise evidence when available; source references remain optional. Existing
+   benchmark/task/metric definitions are required. Do not invent missing IDs or
+   create benchmarks. Report unsupported results to the user. No evaluation
+   deletion, paper identity changes, organization edits, or rank overrides.
+5. Run `pwc paper edit preview PAPER --file edits.json`, inspect the before/after
+   changes, then `pwc paper edit submit PAPER --file edits.json`. Publication is
+   immediate: no per-batch browser approval. Respect the user's requested scope.
+   A batch succeeds completely or makes no changes. The response includes status
+   published and a link to the paper's history.
+6. Retry an uncertain network result using the exact same document and retry key.
+   A 409 means changed data or a reused key with different edits. Fetch a fresh
+   export, preserve others' edits, and reconcile. Ask the user if the same score
+   has conflicting corrections. Once you intentionally revise a previously
+   submitted batch, use a fresh export/key. A 403 may mean expired authorization,
+   suspension, or insufficient scope: read the error; do not broaden access.
+   A 429 indicates the shared account limit: 20 distinct papers per UTC day and
+   30 publications per minute. Do not work around account limits.
+7. `pwc auth status --paper PAPER` shows local expiry metadata (revocation is
+   checked by the server on use). `pwc auth logout --paper PAPER` revokes access.
+   If authorization expires, keep the prepared file and request browser login
+   again. Renewing authorization does not require discarding a valid edit document.
+
+Credentials are stored in owner-only files under ~/.config/pwc/edit-credentials,
+separately for each API base URL and paper. They never belong in a prompt, edit
+file, repository, or command argument. The CLI does not follow edit redirects.

standalone_cli/entrypoint.py

@@ -0,0 +1,3 @@
+from pwc_cli.cli import main
+
+raise SystemExit(main())

standalone_cli/install.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Install one checksum-verified prebuilt pwc CLI artifact."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import http.client
+import json
+import os
+import platform
+import re
+import shlex
+import shutil
+import stat
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+DEFAULT_RELEASE_ORIGIN = "https://github.com/huggingface/pwc-cli/releases/download"
+DEFAULT_LATEST_RELEASE_URL = (
+    "https://api.github.com/repos/huggingface/pwc-cli/releases/latest"
+)
+VERSION_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class NetworkError(Exception):
+    """A concise installer networking failure."""
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--version",
+        help="install an explicit release version instead of the latest release",
+    )
+    parser.add_argument("--prefix", type=Path, default=Path.home() / ".local")
+    parser.add_argument(
+        "--release-origin",
+        default=DEFAULT_RELEASE_ORIGIN,
+    )
+    parser.add_argument(
+        "--latest-release-url",
+        default=DEFAULT_LATEST_RELEASE_URL,
+        help=argparse.SUPPRESS,
+    )
+    return parser.parse_args(argv)
+
+
+def _open(url: str):
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "pwc-cli-installer",
+        },
+    )
+    try:
+        return urllib.request.urlopen(request, timeout=30)
+    except (urllib.error.URLError, TimeoutError) as error:
+        reason = str(getattr(error, "reason", error)).replace("\n", " ")
+        raise NetworkError(reason) from error
+
+
+def _validate_version(version: str) -> str:
+    if not VERSION_RE.fullmatch(version):
+        raise SystemExit(f"invalid release version: {version}")
+    return version
+
+
+def _read_response(response, maximum_bytes: int) -> bytes:
+    try:
+        contents = response.read(maximum_bytes + 1)
+    except (OSError, http.client.HTTPException) as error:
+        raise NetworkError(str(error)) from error
+    if len(contents) > maximum_bytes:
+        raise NetworkError("response was unexpectedly large")
+    return contents
+
+
+def resolve_version(explicit_version: str | None, latest_release_url: str) -> str:
+    if explicit_version:
+        return _validate_version(explicit_version)
+    try:
+        with _open(latest_release_url) as response:
+            payload = json.loads(_read_response(response, 1024 * 1024))
+        tag = payload["tag_name"]
+    except NetworkError:
+        raise
+    except (KeyError, TypeError, ValueError) as error:
+        raise NetworkError("latest release response was invalid") from error
+    prefix = "pwc-cli-"
+    if not isinstance(tag, str) or not tag.startswith(prefix):
+        raise NetworkError("latest release tag was invalid")
+    try:
+        return _validate_version(tag.removeprefix(prefix))
+    except SystemExit as error:
+        raise NetworkError("latest release tag was invalid") from error
+
+
+def _download(url: str, destination: Path) -> None:
+    with _open(url) as response, destination.open("wb") as output:
+        while True:
+            try:
+                chunk = response.read(1024 * 1024)
+            except (OSError, http.client.HTTPException) as error:
+                raise NetworkError(str(error)) from error
+            if not chunk:
+                break
+            output.write(chunk)
+
+
+def _read_checksum(url: str) -> str:
+    with _open(url) as response:
+        contents = _read_response(response, 4096)
+    try:
+        checksum = contents.decode("ascii", errors="strict").split()[0]
+    except (IndexError, UnicodeDecodeError) as error:
+        raise SystemExit("artifact checksum file was invalid") from error
+    if len(checksum) != 64 or any(
+        character not in "0123456789abcdefABCDEF" for character in checksum
+    ):
+        raise SystemExit("artifact checksum file was invalid")
+    return checksum.lower()
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as artifact:
+        for chunk in iter(lambda: artifact.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _install_atomically(artifact: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    file_descriptor, temporary_name = tempfile.mkstemp(
+        prefix=".pwc-install-", dir=destination.parent
+    )
+    os.close(file_descriptor)
+    temporary = Path(temporary_name)
+    try:
+        shutil.copy2(artifact, temporary)
+        temporary.chmod(
+            temporary.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        )
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def report_path(bin_directory: Path, path_value: str | None = None) -> None:
+    path_value = os.environ.get("PATH", "") if path_value is None else path_value
+    expanded_bin = bin_directory.expanduser().resolve()
+    entries = {
+        Path(entry).expanduser().resolve()
+        for entry in path_value.split(os.pathsep)
+        if entry
+    }
+    display = (
+        "~/.local/bin"
+        if expanded_bin == (Path.home() / ".local/bin").resolve()
+        else str(bin_directory)
+    )
+    shell_path = (
+        '"$HOME/.local/bin:$PATH"'
+        if display == "~/.local/bin"
+        else f'{shlex.quote(str(expanded_bin))}:"$PATH"'
+    )
+    if expanded_bin in entries:
+        print(f"{display} is on PATH", flush=True)
+        return
+    print(f"warning: {display} is not on PATH", file=sys.stderr, flush=True)
+    print(
+        f"Add this to ~/.profile: export PATH={shell_path}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def _print_network_error(error: NetworkError) -> None:
+    message = str(error).replace("\r", " ").replace("\n", " ")
+    print(f"pwc installer: network error: {message}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        version = resolve_version(args.version, args.latest_release_url)
+    except NetworkError as error:
+        _print_network_error(error)
+        return 3
+
+    machine = platform.machine().lower()
+    system = platform.system().lower()
+    machine = {"amd64": "x86_64", "aarch64": "arm64"}.get(machine, machine)
+    supported = {
+        ("linux", "x86_64"),
+        ("darwin", "x86_64"),
+        ("darwin", "arm64"),
+    }
+    if (system, machine) not in supported:
+        raise SystemExit(f"unsupported platform: {system}-{machine}")
+    artifact = f"pwc-{version}-{system}-{machine}"
+    base = f"{args.release_origin.rstrip('/')}/pwc-cli-{version}"
+    try:
+        with tempfile.TemporaryDirectory(prefix="pwc-install-") as directory:
+            target = Path(directory) / artifact
+            _download(f"{base}/{artifact}", target)
+            checksum = _read_checksum(f"{base}/{artifact}.sha256")
+            if _sha256(target) != checksum:
+                raise SystemExit("artifact checksum verification failed")
+            destination = args.prefix / "bin" / "pwc"
+            _install_atomically(target, destination)
+    except NetworkError as error:
+        _print_network_error(error)
+        return 3
+    report_path(destination.parent)
+    os.execv(destination, [str(destination), "version"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

standalone_cli/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "pwc-cli"
+version = "0.4.6"
+description = "Papers With Code research and paper-editing CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = []
+
+[project.scripts]
+pwc = "pwc_cli.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pwc_cli"]

standalone_cli/scripts/check_contract.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Fail CI when parser, sandbox guide, or public-skill inventory drifts."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPOSITORY = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPOSITORY / "standalone_cli" / "src"))
+
+from pwc_cli.cli import build_parser  # noqa: E402
+
+EDIT_COMMANDS = ("auth login", "auth status", "auth logout", "paper edit export", "paper edit preview", "paper edit submit")
+
+COMMANDS = (
+    "search",
+    "paper info",
+    "paper evaluations",
+    "paper read",
+    "paper list",
+    "paper recent",
+    "paper trending",
+    "paper related",
+    "paper lineage list",
+    "task",
+    "task list",
+    "method",
+    "method list",
+    "conference",
+    "conference list",
+    "organization",
+    "organization list",
+    "framework",
+    "framework list",
+    "benchmark",
+    "benchmark list",
+    "skills add",
+    "version",
+)
+
+RESEARCH_COMMANDS = tuple(command for command in COMMANDS if command != "skills add")
+
+
+def parser_commands() -> set[str]:
+    parser = build_parser()
+    discovered: set[str] = set()
+
+    def visit(current, prefix: str = ""):
+        for action in current._actions:
+            choices = getattr(action, "choices", None)
+            if not isinstance(choices, dict):
+                continue
+            for name, child in choices.items():
+                command = f"{prefix} {name}".strip()
+                nested = any(
+                    isinstance(getattr(item, "choices", None), dict)
+                    for item in child._actions
+                )
+                if nested:
+                    if "handler" in child._defaults:
+                        discovered.add(command)
+                    visit(child, command)
+                else:
+                    discovered.add(command)
+
+    visit(parser)
+    return discovered
+
+
+def main() -> int:
+    expected = set(COMMANDS) | set(EDIT_COMMANDS)
+    if parser_commands() != expected:
+        raise SystemExit("standalone parser command inventory drifted")
+    skill = (REPOSITORY / "standalone_cli" / "SKILL.md").read_text()
+    for command in EDIT_COMMANDS:
+        if f"pwc {command}" not in skill:
+            raise SystemExit(f"missing edit command: {command}")
+    for command in RESEARCH_COMMANDS:
+        if command == "version":
+            continue
+        invocation = f"pwc {command}"
+        if invocation not in skill:
+            raise SystemExit(f"missing read-only inventory entry: {invocation}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

standalone_cli/src/pwc_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Standalone Papers With Code client."""
+
+__version__ = "0.4.6"
+API_CONTRACT_VERSION = "v1"

standalone_cli/src/pwc_cli/__main__.py

@@ -0,0 +1,3 @@
+from pwc_cli.cli import main
+
+raise SystemExit(main())

standalone_cli/src/pwc_cli/edit_credentials.py

@@ -0,0 +1,66 @@
+"""Private per-origin, per-paper credential files. Secrets never enter edit documents."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import stat
+import tempfile
+
+from pwc_cli.transport import ResponseError
+
+
+class CredentialStore:
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+        self.root = Path.home() / ".config" / "pwc" / "edit-credentials"
+
+    def path(self, paper_id: int) -> Path:
+        key = hashlib.sha256(f"{self.base_url}:{paper_id}".encode()).hexdigest()
+        return self.root / f"{key}.json"
+
+    def save(self, paper_id: int, credential: dict) -> None:
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        info = self.root.lstat()
+        if (
+            not stat.S_ISDIR(info.st_mode)
+            or info.st_uid != os.getuid()
+            or info.st_mode & 0o077
+        ):
+            raise ResponseError(
+                "Credential directory must be owned by you with mode 0700"
+            )
+        fd, name = tempfile.mkstemp(dir=self.root)
+        try:
+            with os.fdopen(fd, "w") as handle:
+                json.dump({**credential, "base_url": self.base_url}, handle)
+            os.replace(name, self.path(paper_id))
+        finally:
+            if os.path.exists(name):
+                os.unlink(name)
+
+    def load(self, paper_id: int) -> dict:
+        path = self.path(paper_id)
+        try:
+            fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+        except FileNotFoundError as error:
+            raise ResponseError(
+                "No authorization for this paper and API. Run pwc auth login --paper PAPER"
+            ) from error
+        with os.fdopen(fd) as handle:
+            info = os.fstat(handle.fileno())
+            if (
+                not stat.S_ISREG(info.st_mode)
+                or info.st_uid != os.getuid()
+                or info.st_mode & 0o077
+            ):
+                raise ResponseError(
+                    "Credential file must be owned by you with mode 0600"
+                )
+            value = json.load(handle)
+        if value.get("base_url") != self.base_url or value.get("paper_id") != paper_id:
+            raise ResponseError("Credential origin or paper does not match")
+        return value
+
+    def remove(self, paper_id: int) -> None:
+        self.path(paper_id).unlink(missing_ok=True)

standalone_cli/src/pwc_cli/edit_transport.py

@@ -0,0 +1,72 @@
+"""Origin-bound edit transport. Never forwards a credential through a redirect."""
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from pwc_cli.transport import (
+    HTTPStatusError,
+    MAX_RESPONSE_BYTES,
+    ResponseError,
+    TransportError,
+)
+from pwc_cli import __version__
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def edit_base_url(value: str) -> str:
+    parsed = urllib.parse.urlsplit(value)
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ResponseError(
+            "Edit API URL must not contain credentials, query, or fragment"
+        )
+    if parsed.scheme != "https" and not (
+        parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+    ):
+        raise ResponseError(
+            "Editing requires HTTPS (HTTP is allowed only on loopback for development)"
+        )
+    if not parsed.hostname:
+        raise ResponseError("Invalid edit API origin")
+    return value.rstrip("/")
+
+
+class EditClient:
+    def __init__(self, base_url: str, token: str | None = None):
+        self.base_url = edit_base_url(base_url)
+        self.token = token
+
+    def request(self, method: str, path: str, payload=None):
+        if not path.startswith("/") or path.startswith("//") or ".." in path:
+            raise ResponseError("Invalid edit endpoint")
+        headers = {"Accept": "application/json", "User-Agent": f"pwc-cli/{__version__}"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        data = None
+        if payload is not None:
+            data = json.dumps(payload, allow_nan=False).encode()
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(
+            self.base_url + path, method=method, data=data, headers=headers
+        )
+        try:
+            with urllib.request.build_opener(NoRedirect()).open(
+                request, timeout=60
+            ) as response:
+                body = response.read(MAX_RESPONSE_BYTES + 1)
+                if len(body) > MAX_RESPONSE_BYTES:
+                    raise ResponseError("Edit response exceeded the byte limit")
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as error:
+            raise HTTPStatusError(
+                error.code, error.read(4096).decode("utf-8", errors="replace")
+            ) from error
+        except urllib.error.URLError as error:
+            raise TransportError(f"Edit API request failed: {error.reason}") from error
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ResponseError("Edit API returned invalid JSON") from error

standalone_cli/src/pwc_cli/edits.py

@@ -0,0 +1,154 @@
+"""Authenticated paper edits for humans and coding agents."""
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import sys
+import time
+from urllib.parse import urlsplit
+import webbrowser
+
+from pwc_cli.edit_credentials import CredentialStore
+from pwc_cli.edit_transport import EditClient, edit_base_url
+from pwc_cli.transport import ResponseError
+
+
+class EditUsageError(ValueError):
+    pass
+
+
+def paper_id(reference, client):
+    from pwc_cli.cli import _resolve_paper
+
+    reference = _resolve_paper(reference, client)
+    if reference.isdigit():
+        return int(reference)
+    value = client.get(f"papers/{reference}").json().get("id")
+    if not value:
+        raise ResponseError("Paper response did not include its database ID")
+    return int(value)
+
+
+def auth(args, client):
+    base = edit_base_url(client.base_url)
+    target = paper_id(args.paper, client)
+    store = CredentialStore(base)
+    if args.auth_command == "login":
+        api = EditClient(base)
+        start = api.request("POST", "/paper-edit-authorizations", {"paper_id": target})
+        origin = urlsplit(base)
+        path = start["verification_path"]
+        if not path.startswith("/authorize-paper-edit/") or "?" in path or "#" in path:
+            raise ResponseError("Invalid browser authorization path")
+        url = f"{origin.scheme}://{origin.netloc}{path}"
+        print(
+            f"Authorize paper {target} at {url}\nCheck that the browser shows code {start['user_code']}.\nAccess expires after one hour; edits publish immediately.",
+            file=sys.stderr,
+        )
+        if not args.no_browser:
+            webbrowser.open(url)
+        deadline = time.monotonic() + min(int(start["expires_in"]), 600)
+        while time.monotonic() < deadline:
+            result = api.request(
+                "POST",
+                "/paper-edit-authorizations/token",
+                {"device_code": start["device_code"]},
+            )
+            if result.get("status") == "authorized":
+                if result.get("paper_id") != target or not result.get("access_token"):
+                    raise ResponseError(
+                        "Authorization returned the wrong paper or no credential"
+                    )
+                store.save(target, result)
+                print(
+                    json.dumps(
+                        {
+                            "status": "authorized",
+                            "paper_id": target,
+                            "username": result["username"],
+                            "expires_at": result["expires_at"],
+                        }
+                    )
+                )
+                return 0
+            if result.get("status") != "authorization_pending":
+                raise ResponseError("Unexpected authorization response")
+            time.sleep(max(1, min(int(start["interval"]), 10)))
+        raise EditUsageError("Browser authorization timed out. Run login again.")
+    saved = store.load(target)
+    if args.auth_command == "status":
+        print(
+            json.dumps(
+                {
+                    "paper_id": target,
+                    "api": base,
+                    "username": saved["username"],
+                    "expires_at": saved["expires_at"],
+                    "expired": datetime.fromisoformat(saved["expires_at"])
+                    <= datetime.now(timezone.utc),
+                }
+            )
+        )
+    else:
+        EditClient(base, saved["access_token"]).request("POST", "/paper-edit-logout")
+        store.remove(target)
+        print("Paper authorization revoked.")
+    return 0
+
+
+def edit(args, client):
+    base = edit_base_url(client.base_url)
+    target = paper_id(args.paper, client)
+    saved = CredentialStore(base).load(target)
+    if datetime.fromisoformat(saved["expires_at"]) <= datetime.now(timezone.utc):
+        raise EditUsageError(
+            "Authorization expired. Run pwc auth login --paper PAPER again; keep your edit document."
+        )
+    api = EditClient(base, saved["access_token"])
+    if args.edit_command == "export":
+        document = api.request("GET", f"/papers/{target}/edit-document")
+        with Path(args.output).open("x") as handle:
+            json.dump(document, handle, indent=2)
+            handle.write("\n")
+        print(
+            f"Exported paper {target} to {args.output}. Add explicit operations; current is reference material only."
+        )
+        return 0
+    with Path(args.file).open("rb") as handle:
+        raw = handle.read(1_048_577)
+    if len(raw) > 1_048_576:
+        raise EditUsageError("Edit documents must be at most 1 MiB")
+    document = json.loads(raw)
+    if document.get("paper_id") != target:
+        raise EditUsageError("Document targets a different paper")
+    document.pop("current", None)
+    suffix = "/preview" if args.edit_command == "preview" else ""
+    result = api.request("POST", f"/papers/{target}/edits{suffix}", document)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+def add_commands(commands, paper_commands):
+    parser = commands.add_parser("auth", help="authorize one-hour edits to one paper")
+    sub = parser.add_subparsers(dest="auth_command", required=True)
+    for name in ("login", "status", "logout"):
+        command = sub.add_parser(name)
+        command.add_argument("--paper", required=True)
+        if name == "login":
+            command.add_argument(
+                "--no-browser",
+                action="store_true",
+                help="print the authorization link without opening a browser",
+            )
+        command.set_defaults(handler=auth)
+    parser = paper_commands.add_parser(
+        "edit", help="export, preview, or publish an atomic paper edit"
+    )
+    sub = parser.add_subparsers(dest="edit_command", required=True)
+    for name in ("export", "preview", "submit"):
+        command = sub.add_parser(name)
+        command.add_argument("paper")
+        command.add_argument(
+            "--output" if name == "export" else "--file", required=True
+        )
+        command.set_defaults(handler=edit)

standalone_cli/src/pwc_cli/queries.py

@@ -0,0 +1,179 @@
+"""In-process access to the CLI's read-only research queries.
+
+Embedders such as the Papers With Code MCP server run the exact CLI handlers
+through the CLI's own parser. Every flag, default, validation rule, and JSON
+payload therefore stays identical to ``pwc ... --json`` without a subprocess,
+stdout capture, or a second implementation of the query logic.
+
+Each call owns its parser and result sink, so concurrent callers never share
+state. Only read-only research commands are reachable; authentication, paper
+editing, skill installation, and version display are refused.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+from datetime import date
+from typing import Any
+
+from pwc_cli.cli import Parser, UsageError, build_parser
+from pwc_cli.transport import ResponseError
+
+Command = tuple[str, ...]
+
+READ_ONLY_COMMANDS: tuple[Command, ...] = (
+    ("search",),
+    ("paper", "info"),
+    ("paper", "evaluations"),
+    ("paper", "read"),
+    ("paper", "list"),
+    ("paper", "recent"),
+    ("paper", "trending"),
+    ("paper", "related"),
+    ("paper", "lineage", "list"),
+    ("task",),
+    ("task", "list"),
+    ("method",),
+    ("method", "list"),
+    ("conference",),
+    ("conference", "list"),
+    ("organization",),
+    ("organization", "list"),
+    ("framework",),
+    ("framework", "list"),
+    ("benchmark",),
+    ("benchmark", "list"),
+)
+
+# Flags that only shape terminal rendering. JSON output ignores them, so they
+# have no in-process equivalent.
+PRESENTATION_FLAGS = frozenset({"json", "implementation_coverage", "flat"})
+
+_HIDDEN_ACTIONS = (
+    argparse._SubParsersAction,
+    argparse._HelpAction,
+    argparse._VersionAction,
+)
+
+
+class _StrictParser(Parser):
+    """Raise ``UsageError`` for invalid arguments instead of exiting."""
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        raise UsageError(message)
+
+
+def _command_label(command: Command) -> str:
+    return " ".join(("pwc", *command))
+
+
+def command_parser(
+    command: Command, parser: argparse.ArgumentParser | None = None
+) -> argparse.ArgumentParser:
+    """Return the subparser that handles ``command``."""
+    current = parser or build_parser(parser_class=_StrictParser)
+    for name in command:
+        subparsers = next(
+            (
+                action
+                for action in current._actions
+                if isinstance(action, argparse._SubParsersAction)
+            ),
+            None,
+        )
+        if subparsers is None or name not in subparsers.choices:
+            raise KeyError(f"unknown command: {_command_label(command)}")
+        current = subparsers.choices[name]
+    return current
+
+
+def query_options(command: Command) -> dict[str, argparse.Action]:
+    """Research options of one command keyed by destination.
+
+    Presentation-only flags, help, version, and nested command selectors are
+    excluded, leaving exactly the options an embedder must expose.
+    """
+    parser = command_parser(command)
+    return {
+        action.dest: action
+        for action in parser._actions
+        if not isinstance(action, _HIDDEN_ACTIONS)
+        and action.dest not in PRESENTATION_FLAGS
+    }
+
+
+def _text(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)
+
+
+def build_argv(command: Command, options: Mapping[str, Any]) -> list[str]:
+    """Translate structured options into the argv the CLI parser expects.
+
+    ``None`` leaves a flag at its CLI default. Booleans toggle ``store_true``
+    flags. Lists repeat ``append`` flags or join comma-separated values, and
+    mappings expand to repeated ``NAME=VALUE`` entries.
+    """
+    actions = query_options(command)
+    unknown = sorted(set(options) - set(actions))
+    if unknown:
+        raise UsageError(
+            f"unknown option(s) for {_command_label(command)}: {', '.join(unknown)}"
+        )
+    argv = list(command)
+    positionals: list[str] = []
+    for dest, action in actions.items():
+        value = options.get(dest)
+        if value is None:
+            continue
+        if not action.option_strings:
+            positionals.append(_text(value))
+            continue
+        flag = action.option_strings[0]
+        if isinstance(action, argparse._StoreTrueAction):
+            if value is True:
+                argv.append(flag)
+            elif value is not False:
+                raise UsageError(f"{flag} expects a boolean")
+            continue
+        if isinstance(value, Mapping):
+            value = [f"{name}={_text(item)}" for name, item in value.items()]
+        values = list(value) if isinstance(value, (list, tuple, set)) else [value]
+        if isinstance(action, argparse._AppendAction):
+            for item in values:
+                argv.extend((flag, _text(item)))
+        elif values:
+            argv.extend((flag, ",".join(_text(item) for item in values)))
+    if positionals:
+        argv.append("--")
+        argv.extend(positionals)
+    return argv
+
+
+def query(command: Command, options: Mapping[str, Any], client: Any) -> Any:
+    """Run one read-only CLI command in-process and return its JSON ``data``.
+
+    ``client`` must provide ``get(path, params) -> Response`` like
+    :class:`pwc_cli.transport.Client`. Invalid options raise ``UsageError``;
+    catalog failures raise the CLI's ``TransportError`` or ``ResponseError``.
+    """
+    command = tuple(command)
+    if command not in READ_ONLY_COMMANDS:
+        raise UsageError(
+            f"{_command_label(command)} is not a read-only research command"
+        )
+    argv = build_argv(command, options)
+    args = build_parser(parser_class=_StrictParser).parse_args(argv)
+    sink: list[Any] = []
+    args.json = True
+    args.result_sink = sink
+    args.handler(args, client)
+    if len(sink) != 1:
+        raise ResponseError(
+            f"{_command_label(command)} did not produce one JSON result"
+        )
+    return sink[0]

standalone_cli/src/pwc_cli/skills.py

@@ -0,0 +1,294 @@
+"""Generate and install the pwc CLI skill for AI coding agents."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from pwc_cli import __version__
+
+SKILL_NAME = "pwc-cli"
+CENTRAL_LOCAL = Path(".agents/skills")
+CENTRAL_GLOBAL = Path("~/.agents/skills")
+CLAUDE_LOCAL = Path(".claude/skills")
+CLAUDE_GLOBAL = Path("~/.claude/skills")
+
+_DESCRIPTION = (
+    "Papers With Code CLI (`pwc`) for searching and reading AI/ML papers, "
+    "discovering recent and trending research, finding related work and paper "
+    "lineage, browsing tasks, methods, conferences, organizations, frameworks, "
+    "and benchmark leaderboards, and submitting authenticated paper edits "
+    "through the public Papers With Code catalog. Use whenever the user asks to "
+    "find papers, survey literature, compare research, inspect an arXiv paper, "
+    "explore AI/ML taxonomy or conferences, discover benchmarks or "
+    "state-of-the-art models, or mentions Papers With Code, `pwc`, or `pwc-cli`."
+)
+
+_INTRODUCTION = """
+Research commands query the public [Papers With Code](https://paperswithcode.co) catalog anonymously.
+Paper editing requires explicit browser authorization through `pwc auth login --paper PAPER`.
+Run `pwc --help` or a nested `--help` command when the live parser and this
+skill disagree; the parser is authoritative.
+
+Use compact output for reading and discovery. Add `--json` for programmatic
+filtering, joining, or schema-dependent processing.
+
+When the user identifies an author, prefer repeatable structured
+`pwc paper list --author AUTHOR` filters. Add `--search TEXT` for stated topic
+terms and explicit `--order-by date_published --order-dir desc` for newest or
+recent work. Author references accept an exact normalized name, numeric ID, or
+`@HF_USERNAME`; repeated authors use AND semantics.
+
+Publication date ranges are inclusive: use `--start-date YYYY-MM-DD` and
+`--end-date YYYY-MM-DD` with `pwc search` or `pwc paper list`; the start date
+must not be later than `--end-date`. The combined flags are
+`--start-date YYYY-MM-DD --end-date YYYY-MM-DD`.
+
+Paper discovery commands accept `--implementation-coverage` to add official
+implementation status and total linked repository count columns. JSON and
+`pwc paper info` always include both fields. Use
+`--has-official-implementation` with `pwc search` or `pwc paper list` to require
+a catalog-linked official repository; these filters fail closed if unconfirmed.
+
+Use `pwc benchmark --name NAME --max-parameters SIZE` to keep models at or
+below an inclusive parameter limit. SIZE accepts values such as `500M`, `1.5B`,
+`3B`, and raw integers. Models without one consistent parameter count are
+excluded from constrained results.
+
+`PAPER` accepts a modern or legacy arXiv ID, a numeric external-paper ID, or an
+exact paper title. Quote titles containing spaces. Title matching is
+case-insensitive but exact; ambiguous titles fail with their matching IDs.
+When `pwc paper info` or `pwc paper read` names a paper Papers With Code has
+not indexed, stderr shows "Not indexed on Papers With Code — available at:"
+with public links and metadata before the usual not-found error; cite those
+links, not a Papers With Code page.
+"""
+
+_WORKFLOW = """
+## Research workflow
+
+1. Use `pwc benchmark list --task TASK` to discover active benchmarks, then
+   `pwc benchmark --name NAME` to inspect a leaderboard. Add
+   `--max-parameters SIZE` when model size is part of the request.
+2. Use `pwc paper info` to inspect promising results. Add
+   `--include-resources` when repositories, project pages, or Hugging Face
+   artifacts matter.
+3. Use exact `pwc paper list --author`, `--task`, `--method`, `--conference`,
+   `--framework`, and `--organization` filters for known identities or catalog
+   associations. Combine them to require every association; do not substitute
+   a keyword search. Add `--search` for title or abstract topic terms.
+4. Use `pwc search` for broader discovery, then `pwc paper read` for primary
+   evidence.
+5. Expand the literature with `pwc paper related` and use
+   `pwc paper lineage list` when model or method ancestry matters.
+6. Preserve paper titles, identifiers, and URLs so claims remain traceable.
+
+## Output and limits
+
+- Interactive output is optimized for people. Benchmark lists remain aligned
+  when captured; other captured list output uses lossless TSV. Add `--json` for
+  structured agent or script consumption.
+- Stable exit codes are `0` success, `2` invalid usage, `3` network/server
+  failure, and `4` invalid API response.
+- `PWC_API_URL` may select another compatible v1 endpoint. The default is
+  `https://paperswithcode.co/api/v1`.
+- Catalog-filtered paper lists fail closed unless the server confirms every
+  requested filter; never treat results from an older server as filtered.
+- Parameter-filtered benchmark details fail closed unless the server confirms
+  parameter-filter support and every returned model satisfies the limit.
+
+The research commands contain no authentication, catalog mutation, ingestion,
+publication, image, embedding, CRON, or infrastructure-maintenance operations.
+"""
+
+
+class SkillInstallError(Exception):
+    """An invalid or unsafe skill installation request."""
+
+
+def _subcommand_help(action: argparse._SubParsersAction, name: str) -> str:
+    for choice in action._choices_actions:
+        if choice.dest == name:
+            return str(choice.help or "")
+    return ""
+
+
+def _command_signature(parser: argparse.ArgumentParser) -> str:
+    parts: list[str] = []
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            continue
+        if action.dest == "help":
+            continue
+        if not action.option_strings:
+            parts.append(str(action.metavar or action.dest).upper())
+            continue
+        option = next(
+            (item for item in action.option_strings if item.startswith("--")),
+            action.option_strings[0],
+        )
+        if action.nargs == 0:
+            parts.append(f"[{option}]")
+            continue
+        if action.choices:
+            value = "|".join(str(choice) for choice in action.choices)
+        else:
+            value = str(action.metavar or action.dest).upper()
+        parts.append(f"[{option} {value}]")
+    return " ".join(parts)
+
+
+def _command_entries(
+    parser: argparse.ArgumentParser, prefix: tuple[str, ...] = ()
+) -> list[str]:
+    entries: list[str] = []
+    for action in parser._actions:
+        if not isinstance(action, argparse._SubParsersAction):
+            continue
+        for name, child in action.choices.items():
+            path = (*prefix, name)
+            if "handler" in child._defaults:
+                signature = _command_signature(child)
+                invocation = " ".join(("pwc", *path, signature)).rstrip()
+                help_text = _subcommand_help(action, name)
+                suffix = f" — {help_text.rstrip('.')}" if help_text else ""
+                entries.append(f"- `{invocation}`{suffix}.")
+            entries.extend(_command_entries(child, path))
+    return entries
+
+
+def build_skill_md() -> str:
+    """Build a Skill matching the commands in the installed pwc version."""
+    from pwc_cli.cli import build_parser
+
+    commands = "\n".join(_command_entries(build_parser()))
+    return (
+        "---\n"
+        f"name: {SKILL_NAME}\n"
+        f'description: "{_DESCRIPTION}"\n'
+        "---\n\n"
+        f"Generated with `pwc v{__version__}`. Run "
+        "`pwc skills add --force` to regenerate.\n"
+        f"{_INTRODUCTION}\n"
+        "## Commands\n\n"
+        f"{commands}\n"
+        f"{_WORKFLOW}\n{_EDIT_WORKFLOW}"
+    )
+
+
+def _remove_existing(path: Path, force: bool) -> None:
+    if not (path.exists() or path.is_symlink()):
+        return
+    if not force:
+        raise SkillInstallError(
+            f"skill already exists at {path}; rerun with --force to overwrite"
+        )
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    else:
+        path.unlink()
+
+
+def _install_to(skills_dir: Path, force: bool) -> Path:
+    skills_dir = skills_dir.expanduser().resolve()
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    target = skills_dir / SKILL_NAME
+    _remove_existing(target, force)
+    temporary = Path(tempfile.mkdtemp(prefix=f".{SKILL_NAME}-", dir=skills_dir))
+    try:
+        (temporary / "SKILL.md").write_text(build_skill_md(), encoding="utf-8")
+        os.replace(temporary, target)
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+    return target
+
+
+def _link_to(skills_dir: Path, installed: Path, force: bool) -> Path:
+    skills_dir = skills_dir.expanduser().resolve()
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    link = skills_dir / SKILL_NAME
+    _remove_existing(link, force)
+    link.symlink_to(os.path.relpath(installed, skills_dir), target_is_directory=True)
+    return link
+
+
+def skills_add(args: argparse.Namespace, _client: object) -> int:
+    """Install the generated pwc skill in central and optional harness paths."""
+    if args.dest is not None and (args.global_ or args.claude):
+        raise SkillInstallError("--dest cannot be combined with --global or --claude")
+
+    if args.dest is not None:
+        installed = _install_to(args.dest, args.force)
+        print(f"Installed '{SKILL_NAME}' to {installed}")
+        return 0
+
+    central_root = CENTRAL_GLOBAL if args.global_ else CENTRAL_LOCAL
+    installed = _install_to(central_root, args.force)
+    print(f"Installed '{SKILL_NAME}' to {installed}")
+
+    if args.claude:
+        claude_root = CLAUDE_GLOBAL if args.global_ else CLAUDE_LOCAL
+        link = _link_to(claude_root, installed, args.force)
+        print(f"Linked '{SKILL_NAME}' for Claude at {link}")
+    return 0
+
+
+_EDIT_WORKFLOW = """
+## Editing one paper
+
+Use this workflow only when the user requests edits. Research commands remain anonymous.
+
+1. Run `pwc auth login --paper PAPER`. Give the user the browser link and code;
+   they sign in with Hugging Face and authorize that paper for one hour. Use
+   `--no-browser` on a remote machine. Never extract, print, or copy credentials.
+2. Run `pwc paper edit export PAPER --output edits.json` (the output must not
+   already exist). It includes paper_id, version, idempotency_key, empty operations,
+   and current reference data. Change operations, not current. Preserve the
+   exported version and retry key. Documents may contain at most 50 operations
+   and 1 MiB of JSON.
+3. Add operations of the form `{"section":"tasks","payload":{"task_ids":[1,2]}}`.
+   A section operation explicitly replaces that section; preserve unrelated links
+   and tags. Omitted sections stay unchanged. Allowed sections and payload keys:
+   tasks/task_ids, methods/method_ids, repositories/repositories,
+   project_pages/project_pages, hf_artifacts/hf_models+hf_datasets+hf_spaces,
+   x_threads/x_threads, source_url/source_url (external papers only), and
+   evaluations. Repository/project-page entries contain url and is_official.
+   x_threads is a list of x.com or twitter.com post URLs in display order (at
+   most 10). Link only posts in which the paper's authors or their organization
+   introduce the paper, never outside accounts; the server captures each post's
+   preview and rejects deleted or protected posts.
+4. For evaluations, an operation without evaluation_id creates a row. Include
+   task_id, dataset_id, metrics (a dictionary of existing metric names to scores),
+   model_name, and the evaluation setup where available. One row can contain
+   multiple metrics. Add evaluation_id to correct an existing row on this paper;
+   omitted update fields stay unchanged. Use source_url and methodology to cite
+   precise evidence when available; source references remain optional. Existing
+   benchmark/task/metric definitions are required. Do not invent missing IDs or
+   create benchmarks. Report unsupported results to the user. No evaluation
+   deletion, paper identity changes, organization edits, or rank overrides.
+5. Run `pwc paper edit preview PAPER --file edits.json`, inspect the before/after
+   changes, then `pwc paper edit submit PAPER --file edits.json`. Publication is
+   immediate: no per-batch browser approval. Respect the user's requested scope.
+   A batch succeeds completely or makes no changes. The response includes status
+   published and a link to the paper's history.
+6. Retry an uncertain network result using the exact same document and retry key.
+   A 409 means changed data or a reused key with different edits. Fetch a fresh
+   export, preserve others' edits, and reconcile. Ask the user if the same score
+   has conflicting corrections. Once you intentionally revise a previously
+   submitted batch, use a fresh export/key. A 403 may mean expired authorization,
+   suspension, or insufficient scope: read the error; do not broaden access.
+   A 429 indicates the shared account limit: 20 distinct papers per UTC day and
+   30 publications per minute. Do not work around account limits.
+7. `pwc auth status --paper PAPER` shows local expiry metadata (revocation is
+   checked by the server on use). `pwc auth logout --paper PAPER` revokes access.
+   If authorization expires, keep the prepared file and request browser login
+   again. Renewing authorization does not require discarding a valid edit document.
+
+Credentials are stored in owner-only files under ~/.config/pwc/edit-credentials,
+separately for each API base URL and paper. They never belong in a prompt, edit
+file, repository, or command argument. The CLI does not follow edit redirects.
+"""

standalone_cli/src/pwc_cli/transport.py

@@ -0,0 +1,100 @@
+"""Credential-ready anonymous HTTP transport for the public catalog API."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from pwc_cli import __version__
+
+DEFAULT_API_URL = "https://paperswithcode.co/api/v1"
+MAX_RESPONSE_BYTES = 2 * 1024 * 1024
+
+
+class TransportError(RuntimeError):
+    pass
+
+
+class HTTPStatusError(TransportError):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"API request failed ({status}): {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class ResponseError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Response:
+    body: bytes
+    headers: dict[str, str]
+
+    def json(self) -> Any:
+        try:
+            return json.loads(self.body)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ResponseError("API returned invalid JSON") from error
+
+
+class Client:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        credential: str | None = None,
+        timeout: float = 30,
+    ):
+        configured = base_url or os.environ.get("PWC_API_URL") or DEFAULT_API_URL
+        self.base_url = configured.rstrip("/")
+        self.credential = credential
+        self.timeout = timeout
+
+    def get(
+        self, path: str, params: dict[str, object | None] | None = None
+    ) -> Response:
+        query = urllib.parse.urlencode(
+            {
+                key: str(value).lower() if isinstance(value, bool) else value
+                for key, value in (params or {}).items()
+                if value is not None
+            },
+            doseq=True,
+        )
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        if query:
+            url += f"?{query}"
+        headers = {
+            "Accept": "application/json, text/plain;q=0.9",
+            "User-Agent": f"pwc-cli/{__version__}",
+        }
+        if self.credential:
+            headers["Authorization"] = f"Bearer {self.credential}"
+        request = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                length = response.headers.get("Content-Length")
+                if length and int(length) > MAX_RESPONSE_BYTES:
+                    raise ResponseError("API response exceeded the client byte limit")
+                body = response.read(MAX_RESPONSE_BYTES + 1)
+                if len(body) > MAX_RESPONSE_BYTES:
+                    raise ResponseError("API response exceeded the client byte limit")
+                return Response(
+                    body,
+                    {key.lower(): value for key, value in response.headers.items()},
+                )
+        except urllib.error.HTTPError as error:
+            detail = error.read(4096).decode("utf-8", errors="replace")
+            raise HTTPStatusError(error.code, detail) from error
+        except urllib.error.URLError as error:
+            raise TransportError(f"API request failed: {error.reason}") from error
+        except TimeoutError as error:
+            # Read timeouts surface as a bare TimeoutError, not a URLError.
+            raise TransportError("API request timed out") from error
+        except OSError as error:
+            raise TransportError(f"API request failed: {error}") from error

standalone_cli/tests/test_edits.py

@@ -0,0 +1,124 @@
+import json
+import stat
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from pwc_cli.edit_credentials import CredentialStore
+from pwc_cli.edit_transport import EditClient, NoRedirect, edit_base_url
+from pwc_cli.edits import EditUsageError
+from pwc_cli import edits
+from pwc_cli.cli import build_parser
+from pwc_cli.transport import Client, ResponseError
+
+
+def test_credential_origin_paper_and_permissions(tmp_path, monkeypatch):
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    store = CredentialStore("https://paperswithcode.co/api/v1")
+    store.save(1, {"paper_id": 1, "access_token": "secret"})
+    assert stat.S_IMODE(store.path(1).stat().st_mode) == 0o600
+    assert store.load(1)["access_token"] == "secret"
+    with pytest.raises(ResponseError):
+        store.load(2)
+    with pytest.raises(ResponseError):
+        CredentialStore("https://other.example/api/v1").load(1)
+    store.path(1).chmod(0o644)
+    with pytest.raises(ResponseError):
+        store.load(1)
+
+
+def test_edit_transport_rejects_unsafe_origins_and_redirects():
+    for url in (
+        "http://example.org/api/v1",
+        "https://user:pass@example.org/api/v1",
+        "https://example.org/api?token=secret",
+    ):
+        with pytest.raises(ResponseError):
+            edit_base_url(url)
+    assert edit_base_url("http://127.0.0.1:8989/api/v1").startswith("http:")
+    assert (
+        NoRedirect().redirect_request(None, None, 302, "", {}, "https://other.example")
+        is None
+    )
+
+
+def test_submit_omits_reference_material_and_keeps_retry_key(
+    tmp_path, monkeypatch, capsys
+):
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    client = Client()
+    store = CredentialStore(client.base_url)
+    store.save(
+        1,
+        {
+            "paper_id": 1,
+            "access_token": "top-secret",
+            "expires_at": (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(),
+        },
+    )
+    document = {
+        "paper_id": 1,
+        "version": "a" * 64,
+        "idempotency_key": "stable-key",
+        "current": {"private_reference": True},
+        "operations": [{"section": "tasks", "payload": {"task_ids": [3]}}],
+    }
+    path = tmp_path / "edits.json"
+    path.write_text(json.dumps(document))
+    calls = []
+
+    def request(self, method, endpoint, payload=None):
+        calls.append((method, endpoint, payload))
+        return {"status": "published"}
+
+    monkeypatch.setattr(EditClient, "request", request)
+    args = build_parser().parse_args(
+        ["paper", "edit", "submit", "1", "--file", str(path)]
+    )
+    assert edits.edit(args, client) == 0
+    assert calls[0][2]["idempotency_key"] == "stable-key"
+    assert "current" not in calls[0][2]
+    assert "top-secret" not in capsys.readouterr().out
+    document["paper_id"] = 2
+    path.write_text(json.dumps(document))
+    with pytest.raises(EditUsageError):
+        edits.edit(args, client)
+    assert len(calls) == 1
+
+
+def test_login_requires_browser_approval_and_never_prints_token(
+    tmp_path, monkeypatch, capsys
+):
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    responses = iter(
+        [
+            {
+                "device_code": "device-secret",
+                "verification_path": "/authorize-paper-edit/abc",
+                "user_code": "ABC",
+                "expires_in": 600,
+                "interval": 5,
+            },
+            {"status": "authorization_pending"},
+            {
+                "status": "authorized",
+                "paper_id": 1,
+                "username": "alice",
+                "access_token": "access-secret",
+                "expires_at": (
+                    datetime.now(timezone.utc) + timedelta(hours=1)
+                ).isoformat(),
+            },
+        ]
+    )
+    monkeypatch.setattr(EditClient, "request", lambda *a, **kw: next(responses))
+    monkeypatch.setattr(edits.time, "sleep", lambda _: None)
+    monkeypatch.setattr(
+        edits.webbrowser, "open", lambda _: pytest.fail("no-browser ignored")
+    )
+    args = build_parser().parse_args(["auth", "login", "--paper", "1", "--no-browser"])
+    assert edits.auth(args, Client()) == 0
+    output = capsys.readouterr()
+    assert "access-secret" not in output.out + output.err
+    assert "device-secret" not in output.out + output.err
+    assert CredentialStore(Client().base_url).load(1)["access_token"] == "access-secret"

standalone_cli/tests/test_queries.py

@@ -0,0 +1,225 @@
+"""The in-process query layer must mirror ``pwc ... --json`` exactly."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+from contextlib import redirect_stdout
+
+import pytest
+from pwc_cli import queries
+from pwc_cli.cli import UsageError, build_parser, main
+from pwc_cli.transport import Response
+
+NON_RESEARCH_COMMANDS = {
+    ("skills", "add"),
+    ("version",),
+    ("auth", "login"),
+    ("auth", "status"),
+    ("auth", "logout"),
+    ("paper", "edit", "export"),
+    ("paper", "edit", "preview"),
+    ("paper", "edit", "submit"),
+}
+
+EVALUATION_ROWS = [
+    {
+        "id": "1",
+        "model_name": "Small",
+        "metrics": {"mAP": 50.0},
+        "best_rank": 2,
+        "num_parameters": 100_000_000,
+        "paper_id": "1",
+        "task_id": "t",
+        "dataset_id": "9",
+    },
+    {
+        "id": "2",
+        "model_name": "Smaller",
+        "metrics": {"mAP": 60.0},
+        "best_rank": 1,
+        "num_parameters": 50_000_000,
+        "paper_id": "2",
+        "task_id": "t",
+        "dataset_id": "9",
+    },
+]
+
+BENCHMARK_ROUTES = {
+    "datasets/": {"results": [{"id": "9", "name": "COCO", "slug": "coco"}]},
+    "datasets/9/evaluations/": {"count": 2, "results": EVALUATION_ROWS},
+    "evaluations/": {
+        "count": 2,
+        "next_page": None,
+        "parameter_coverage_known": 2,
+        "parameter_coverage_total": 2,
+        "results": EVALUATION_ROWS,
+    },
+}
+
+
+class StubClient:
+    def __init__(self, routes):
+        self.routes = routes
+        self.calls = []
+
+    def get(self, path, params=None):
+        self.calls.append((path, dict(params or {})))
+        return Response(json.dumps(self.routes[path]).encode(), {})
+
+
+def _leaf_commands(parser, prefix=()):
+    for action in parser._actions:
+        if not isinstance(action, argparse._SubParsersAction):
+            continue
+        for name, child in action.choices.items():
+            path = (*prefix, name)
+            if "handler" in child._defaults:
+                yield path
+            yield from _leaf_commands(child, path)
+
+
+def test_read_only_commands_cover_every_research_command():
+    research = set(_leaf_commands(build_parser())) - NON_RESEARCH_COMMANDS
+
+    assert set(queries.READ_ONLY_COMMANDS) == research
+    for command in queries.READ_ONLY_COMMANDS:
+        assert "handler" in queries.command_parser(command)._defaults
+
+
+def test_query_options_exclude_presentation_flags_and_selectors():
+    options = queries.query_options(("benchmark", "list"))
+
+    assert set(options) == {
+        "page",
+        "page_size",
+        "search",
+        "task",
+        "group_by_area",
+        "area",
+        "benchmarks_per_task",
+        "include_descendants",
+        "min_eval_count",
+        "is_open",
+        "order_by",
+        "order_dir",
+    }
+    assert queries.query_options(("search",))["query"].option_strings == []
+
+
+def test_build_argv_translates_structured_options():
+    argv = queries.build_argv(
+        ("benchmark",),
+        {
+            "name": "COCO",
+            "limit": 5,
+            "is_open": True,
+            "require_metrics": ["mAP", "FPS"],
+            "minimum_metrics": {"mAP": 40},
+            "maximum_metrics": {"FPS": 10.5},
+            "pareto": ["mAP:higher", "FPS:lower"],
+            "max_parameters": None,
+        },
+    )
+
+    assert argv == [
+        "benchmark",
+        "--name",
+        "COCO",
+        "--limit",
+        "5",
+        "--is-open",
+        "true",
+        "--require-metrics",
+        "mAP,FPS",
+        "--min",
+        "mAP=40",
+        "--max",
+        "FPS=10.5",
+        "--pareto",
+        "mAP:higher,FPS:lower",
+    ]
+    assert queries.build_argv(
+        ("paper", "list"),
+        {"author": ["Ada", "@ada"], "all_versions": True, "include_resources": False},
+    ) == ["paper", "list", "--author", "Ada", "--author", "@ada", "--all-versions"]
+
+    argv = queries.build_argv(("search",), {"query": "-attention", "limit": 3})
+    assert argv == ["search", "--limit", "3", "--", "-attention"]
+    assert build_parser().parse_args(argv).query == "-attention"
+
+
+def test_query_returns_exactly_the_cli_json_data(monkeypatch, capsys):
+    monkeypatch.setattr("pwc_cli.cli.Client", lambda: StubClient(BENCHMARK_ROUTES))
+    output = io.StringIO()
+    with redirect_stdout(output):
+        assert (
+            main(
+                [
+                    "benchmark",
+                    "--name",
+                    "COCO",
+                    "--max-parameters",
+                    "500M",
+                    "--sort",
+                    "mAP",
+                    "--limit",
+                    "1",
+                    "--json",
+                ]
+            )
+            == 0
+        )
+    printed = json.loads(output.getvalue())
+
+    client = StubClient(BENCHMARK_ROUTES)
+    data = queries.query(
+        ("benchmark",),
+        {"name": "COCO", "max_parameters": "500M", "sort_metric": "mAP", "limit": 1},
+        client,
+    )
+
+    assert {"schema_version": "v1", "data": data} == printed
+    assert data["matched_count"] == 2
+    assert [row["model_name"] for row in data["results"]] == ["Smaller"]
+    assert client.calls[1][1]["max_parameters_exclusive"] == 500_000_001
+    assert capsys.readouterr().out == ""
+
+
+def test_query_raises_usage_errors_instead_of_exiting():
+    client = StubClient({})
+
+    with pytest.raises(UsageError, match="--limit must be 1-100"):
+        queries.query(("search",), {"query": "x", "limit": 500}, client)
+    with pytest.raises(UsageError, match="unknown option"):
+        queries.query(("search",), {"query": "x", "page_size": 5}, client)
+    with pytest.raises(UsageError, match="invalid"):
+        queries.query(("search",), {"query": "x", "start_date": "2026-13-01"}, client)
+    with pytest.raises(UsageError, match="cannot be combined"):
+        queries.query(("task", "list"), {"group_by_area": True, "page": 2}, client)
+    with pytest.raises(UsageError, match="unknown metric"):
+        queries.query(
+            ("benchmark",),
+            {"name": "COCO", "sort_metric": "Latency"},
+            StubClient(BENCHMARK_ROUTES),
+        )
+    assert client.calls == []
+
+
+def test_query_refuses_commands_that_are_not_read_only():
+    for command in (("skills", "add"), ("version",), ("paper", "edit", "export")):
+        with pytest.raises(UsageError, match="not a read-only"):
+            queries.query(command, {}, StubClient({}))
+
+
+def test_query_resolves_metric_aliases_against_the_leaderboard():
+    # Agents ask for "AP" on COCO leaderboards that report "mAP".
+    data = queries.query(
+        ("benchmark",),
+        {"name": "COCO", "sort_metric": "AP:asc"},
+        StubClient(BENCHMARK_ROUTES),
+    )
+
+    assert data["matched_count"] == 2
+    assert [row["model_name"] for row in data["results"]] == ["Small", "Smaller"]