Deploy pwc-cli main (c8a789ed6c1151a2bb9fdd65eb49197eb81daf7a)

README.md

@@ -17,8 +17,3 @@ 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/README.md

@@ -106,6 +106,7 @@ unfiltered leaderboard and a `metric_note` naming the available metrics.
 | `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 |
+| `PWC_MCP_TRUSTED_PROXY_CIDRS` | Comma-separated networks of a non-loopback reverse proxy whose `X-Forwarded-For` is trusted; empty by default |
 | `LOG_LEVEL` | Content-free operational log level |
 
 Native clients may omit `Origin`. Browser requests must match the configured
@@ -115,6 +116,15 @@ 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.
 
+Behind a reverse proxy that does not run on the same host, such as the Hugging
+Face Spaces ingress, set `PWC_MCP_TRUSTED_PROXY_CIDRS` to the proxy's networks.
+A request whose direct peer falls in one of them is limited by the right-most
+`X-Forwarded-For` hop outside those networks; hops further left are
+client-supplied and ignored. Such requests can never name an identity with
+`X-PwC-MCP-Client`. Loopback peers keep the behaviour above. List only
+networks that hold nothing but the proxy: any peer inside them can choose its
+own rate-limit identity.
+
 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

mcp_server/SPEC.md

@@ -108,7 +108,9 @@ openness, and update time. Metric direction is explicit when known.
   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`
+  its own rate-limit identity with `X-PwC-MCP-Client`, optionally trust the
+  right-most untrusted `X-Forwarded-For` hop from peers in
+  `PWC_MCP_TRUSTED_PROXY_CIDRS` (never their `X-PwC-MCP-Client`), and expose cached catalog readiness without making `/health`
   wait on an upstream call.
 
 ## Release

mcp_server/space/README.md

@@ -1,19 +0,0 @@
----
-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/app.py

@@ -185,7 +185,42 @@ 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:
+# Hosts that put the server behind a non-loopback reverse proxy, such as the
+# Hugging Face Spaces ingress, list the proxy's networks in
+# PWC_MCP_TRUSTED_PROXY_CIDRS. A request from such a peer is attributed to the
+# right-most X-Forwarded-For hop outside those networks: hops to its left are
+# client-supplied and can be forged. A proxied request never names its own
+# identity through CLIENT_IDENTITY_HEADER.
+IPNetwork = ipaddress.IPv4Network | ipaddress.IPv6Network
+
+
+def _trusted_proxy_networks(value: str) -> tuple[IPNetwork, ...]:
+    try:
+        return tuple(
+            ipaddress.ip_network(item.strip())
+            for item in value.split(",")
+            if item.strip()
+        )
+    except ValueError as error:
+        raise ValueError(
+            f"PWC_MCP_TRUSTED_PROXY_CIDRS must list CIDR networks: {error}"
+        ) from None
+
+
+def _in_networks(address: str, networks: tuple[IPNetwork, ...]) -> bool:
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    return any(ip in network for network in networks)
+
+
+def _client_address(
+    scope: Scope,
+    headers: Headers,
+    trust_proxy_headers: bool,
+    trusted_proxies: tuple[IPNetwork, ...] = (),
+) -> str:
     client = scope.get("client")
     direct_address = str(client[0]) if client else "unknown"
     try:
@@ -199,6 +234,14 @@ def _client_address(scope: Scope, headers: Headers, trust_proxy_headers: bool) -
         identity = headers.get(CLIENT_IDENTITY_HEADER, "")
         if CLIENT_IDENTITY.fullmatch(identity):
             return f"client:{identity}"
+    elif trust_proxy_headers and _in_networks(direct_address, trusted_proxies):
+        hops = ",".join(headers.getlist("x-forwarded-for")).split(",")
+        for hop in reversed([hop.strip() for hop in hops if hop.strip()]):
+            if not _in_networks(hop, trusted_proxies):
+                try:
+                    return str(ipaddress.ip_address(hop))
+                except ValueError:
+                    break
     return direct_address
 
 
@@ -310,6 +353,7 @@ class RateLimitMiddleware:
         concurrency_limit: int,
         global_concurrency_limit: int,
         trust_proxy_headers: bool,
+        trusted_proxies: tuple[IPNetwork, ...] = (),
         identity_limit: int = 10_000,
     ):
         self.app = app
@@ -318,6 +362,7 @@ class RateLimitMiddleware:
         self.concurrency_limit = concurrency_limit
         self.global_concurrency_limit = global_concurrency_limit
         self.trust_proxy_headers = trust_proxy_headers
+        self.trusted_proxies = trusted_proxies
         self.identity_limit = identity_limit
         self.key = secrets.token_bytes(32)
         self.requests: dict[str, deque[float]] = defaultdict(deque)
@@ -373,7 +418,9 @@ class RateLimitMiddleware:
         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)
+            _client_address(
+                scope, headers, self.trust_proxy_headers, self.trusted_proxies
+            )
         )
         now = time.monotonic()
         limited = False
@@ -482,6 +529,7 @@ def create_app(
     concurrency_limit: int | None = None,
     global_concurrency_limit: int | None = None,
     trust_proxy_headers: bool = True,
+    trusted_proxy_cidrs: str | None = None,
 ) -> ASGIApp:
     if request_limit is None:
         request_limit = _int_env("PWC_MCP_REQUEST_LIMIT", DEFAULT_REQUEST_LIMIT)
@@ -495,6 +543,9 @@ def create_app(
         global_concurrency_limit = _int_env(
             "PWC_MCP_GLOBAL_CONCURRENCY_LIMIT", DEFAULT_GLOBAL_CONCURRENCY_LIMIT
         )
+    if trusted_proxy_cidrs is None:
+        trusted_proxy_cidrs = os.environ.get("PWC_MCP_TRUSTED_PROXY_CIDRS", "")
+    trusted_proxies = _trusted_proxy_networks(trusted_proxy_cidrs)
     hosts = allowed_hosts or _csv_env(
         "PWC_MCP_ALLOWED_HOSTS",
         [
@@ -544,6 +595,7 @@ def create_app(
         concurrency_limit=concurrency_limit,
         global_concurrency_limit=global_concurrency_limit,
         trust_proxy_headers=trust_proxy_headers,
+        trusted_proxies=trusted_proxies,
     )
     wrapped = MCPMethodMiddleware(wrapped)
     wrapped = ResponseSizeLimitMiddleware(wrapped)

mcp_server/tests/test_app.py

@@ -5,7 +5,9 @@ import logging
 from pwc_mcp.app import (
     MAX_RESPONSE_BODY_SIZE,
     ResponseSizeLimitMiddleware,
+    RateLimitMiddleware,
     _client_address,
+    _trusted_proxy_networks,
     create_app,
 )
 from starlette.applications import Starlette
@@ -256,6 +258,109 @@ def test_loopback_first_party_clients_may_name_their_rate_limit_identity():
     assert _client_address({"client": ("127.0.0.1", 1)}, long, True) == "127.0.0.1"
 
 
+HF_PROXIES = _trusted_proxy_networks("10.0.0.0/8, fd00::/8")
+
+
+def test_trusted_proxy_peer_uses_the_rightmost_untrusted_forwarded_hop():
+    def address(peer: str, forwarded: str | None, **extra: str) -> str:
+        values = dict(extra)
+        if forwarded is not None:
+            values["x-forwarded-for"] = forwarded
+        return _client_address(
+            {"client": (peer, 1)}, Headers(values), True, HF_PROXIES
+        )
+
+    assert address("10.1.2.3", "203.0.113.9") == "203.0.113.9"
+    # Hops left of the proxy's own entry are client-supplied and ignored.
+    assert address("10.1.2.3", "198.51.100.1, 203.0.113.9") == "203.0.113.9"
+    # Trusted intermediate proxies are skipped from the right.
+    assert address("10.1.2.3", "203.0.113.9, 10.9.9.9") == "203.0.113.9"
+    assert address("fd00::5", "2001:db8::7, fd00::6") == "2001:db8::7"
+    # Repeated headers are read as one list in arrival order.
+    repeated = Headers(
+        raw=[(b"x-forwarded-for", b"198.51.100.1"), (b"x-forwarded-for", b"203.0.113.9")]
+    )
+    assert (
+        _client_address({"client": ("10.1.2.3", 1)}, repeated, True, HF_PROXIES)
+        == "203.0.113.9"
+    )
+    # Missing, fully trusted, or malformed chains fall back to the proxy peer.
+    assert address("10.1.2.3", None) == "10.1.2.3"
+    assert address("10.1.2.3", "10.4.4.4, 10.5.5.5") == "10.1.2.3"
+    assert address("10.1.2.3", "203.0.113.9, not-an-ip") == "10.1.2.3"
+    # Untrusted peers and disabled trust ignore the header entirely.
+    assert address("192.0.2.4", "203.0.113.9") == "192.0.2.4"
+    assert (
+        _client_address(
+            {"client": ("10.1.2.3", 1)},
+            Headers({"x-forwarded-for": "203.0.113.9"}),
+            False,
+            HF_PROXIES,
+        )
+        == "10.1.2.3"
+    )
+
+
+def test_proxied_hops_never_name_their_own_identity():
+    tagged = {"x-pwc-mcp-client": "chat-0123abcd"}
+    assert (
+        _client_address({"client": ("10.1.2.3", 1)}, Headers(tagged), True, HF_PROXIES)
+        == "10.1.2.3"
+    )
+    forwarded = Headers({**tagged, "x-forwarded-for": "203.0.113.9"})
+    assert (
+        _client_address({"client": ("10.1.2.3", 1)}, forwarded, True, HF_PROXIES)
+        == "203.0.113.9"
+    )
+    # Loopback behaviour is unchanged when proxies are configured.
+    assert (
+        _client_address({"client": ("127.0.0.1", 1)}, Headers(tagged), True, HF_PROXIES)
+        == "client:chat-0123abcd"
+    )
+
+
+def test_trusted_proxy_cidrs_are_opt_in_and_validated(monkeypatch):
+    def middleware(app):
+        while not isinstance(app, RateLimitMiddleware):
+            app = app.app
+        return app
+
+    monkeypatch.delenv("PWC_MCP_TRUSTED_PROXY_CIDRS", raising=False)
+    assert middleware(create_app(StubCatalog())).trusted_proxies == ()
+    monkeypatch.setenv("PWC_MCP_TRUSTED_PROXY_CIDRS", " 10.0.0.0/8 ,fd00::/8,")
+    assert [str(n) for n in middleware(create_app(StubCatalog())).trusted_proxies] == [
+        "10.0.0.0/8",
+        "fd00::/8",
+    ]
+    for invalid in ("10.0.0.1/8", "not-a-cidr", "10.0.0.0/33"):
+        monkeypatch.setenv("PWC_MCP_TRUSTED_PROXY_CIDRS", invalid)
+        try:
+            create_app(StubCatalog())
+        except ValueError as error:
+            assert "PWC_MCP_TRUSTED_PROXY_CIDRS" in str(error)
+            continue
+        raise AssertionError(invalid)
+
+
+def test_clients_behind_a_trusted_proxy_get_separate_rate_limits():
+    app = create_app(
+        StubCatalog(),
+        allowed_hosts=["testserver"],
+        request_limit=1,
+        trusted_proxy_cidrs="10.0.0.0/8",
+    )
+    with TestClient(app, client=("10.1.2.3", 50000)) as client:
+        first = client.post("/mcp", json={}, headers={"x-forwarded-for": "203.0.113.9"})
+        other = client.post("/mcp", json={}, headers={"x-forwarded-for": "203.0.113.10"})
+        repeat = client.post(
+            "/mcp", json={}, headers={"x-forwarded-for": "1.2.3.4, 203.0.113.9"}
+        )
+
+    assert first.status_code != 429
+    assert other.status_code != 429
+    assert repeat.status_code == 429
+
+
 def test_serialized_mcp_response_limit_fails_closed():
     async def oversized(_request):
         return Response(b"x" * (MAX_RESPONSE_BODY_SIZE + 1))