Fix CI and address Server Cards review

Fix pre-commit pyright and the failing build_server_card test, and address
the cubic-dev-ai review threads validated against the SEP-2127 discovery spec.

- _ServerIdentity: declare members read-only so the invariant writable-attr
  protocol stops rejecting Server.version: str vs version: str | None (pyright).
- build_server_card: treat empty version as unset (Server.version defaults to
  "" not None), so the required-version check fires; fix the stale test comment.
- Discovery CORS (spec MUST): allow If-None-Match, expose ETag, and answer the
  OPTIONS preflight browsers send before a cross-origin conditional GET; add
  "OPTIONS" to both discovery routes; update the docs table and add preflight
  tests.
- Docs/tutorials: tutorial001 configures TransportSecuritySettings for the
  advertised public host (default localhost protection would 421); tutorial002
  creates the output directory before writing; tutorial004 resolves relative
  entry URLs against the catalog URL; CatalogEntry.identifier docstring uses the
  correct urn:air:{publisher}:mcp:{name} form; clarify the auth-middleware
  caveat for globally-applied ASGI middleware.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 23994aca-a562-4387-b723-5c4fd4f9a1ca

Author: SamMorrowDrums

docs/advanced/server-cards.md

@@ -71,11 +71,18 @@ standard identity attributes — the low-level `Server` here, but a high-level
 unset — a card cannot exist without them. The `name` you pass is the reverse-DNS
 identifier and is validated against the `namespace/name` pattern.
 
-Because discovery happens *before* authentication, mount both routes **outside**
-any auth middleware — a client must be able to read them unauthenticated. If you
-mount the MCP endpoint at a non-default path, pass a matching `path` to
-`mount_server_card` (the convention is `<streamable-http-url>/server-card`); the
-catalog entry carries the real URL, so any reachable path works.
+Because discovery happens *before* authentication, a client must be able to read
+both routes **unauthenticated**. `mount_server_card` and `mount_ai_catalog` append
+their routes to `app.router.routes`, so they sit *inside* the same app — that
+places them ahead of any per-route auth dependencies, but it does **not** exempt
+them from authentication enforced as global ASGI middleware, which wraps every
+request the app handles. If you gate the app with auth middleware, either exclude
+the discovery paths there (e.g. skip enforcement for the card path and
+`/.well-known/ai-catalog.json`) or serve the card and catalog from a separate,
+unauthenticated sub-app mounted alongside the protected one. If you mount the MCP
+endpoint at a non-default path, pass a matching `path` to `mount_server_card` (the
+convention is `<streamable-http-url>/server-card`); the catalog entry carries the
+real URL, so any reachable path works.
 
 For mounting the MCP app itself into a larger Starlette/FastAPI application, see
 [Add to an existing app](../run/asgi.md).
@@ -101,9 +108,14 @@ with a fixed set of discovery headers (`DISCOVERY_HEADERS`):
 | --- | --- | --- |
 | `Access-Control-Allow-Origin` | `*` | Browser clients fetch cards cross-origin. |
 | `Access-Control-Allow-Methods` | `GET` | Discovery is read-only. |
-| `Access-Control-Allow-Headers` | `Content-Type` | Allows the negotiated `Accept`/content type. |
+| `Access-Control-Allow-Headers` | `Content-Type, If-None-Match` | Allows the negotiated content type and cross-origin conditional GETs. |
+| `Access-Control-Expose-Headers` | `ETag` | Lets browser scripts read the `ETag` to revalidate later. |
 | `Cache-Control` | `public, max-age=3600` | Cards change rarely; let clients and CDNs cache. |
 
+The routes also answer the `OPTIONS` preflight (with `204 No Content` and these
+headers) that a browser sends before a cross-origin conditional GET, because
+`If-None-Match` is not a CORS-safelisted request header.
+
 The card route responds with `application/mcp-server-card+json`; the catalog route
 with `application/ai-catalog+json`.
 

docs_src/server_cards/tutorial001.py

@@ -1,6 +1,7 @@
 from mcp.server.experimental.ai_catalog import mount_ai_catalog, server_card_entry
 from mcp.server.experimental.server_card import build_server_card, mount_server_card
 from mcp.server.lowlevel import Server
+from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared.experimental.ai_catalog import AICatalog
 from mcp.shared.experimental.server_card import Remote, Repository
 
@@ -28,7 +29,17 @@
 # Serve the card next to the MCP endpoint, and advertise it in the host's AI
 # Catalog at `/.well-known/ai-catalog.json`. The catalog entry points at the
 # absolute URL the card is served from.
-app = server.streamable_http_app()
+#
+# The card advertises a public host (`dice.example.com`), so the transport must
+# accept that host: the default streamable-HTTP app auto-enables DNS-rebinding
+# protection scoped to localhost, which would reject requests to the advertised
+# `Host` with `421 Misdirected Request`. Configure the real host and the browser
+# origins allowed to call it.
+security = TransportSecuritySettings(
+    allowed_hosts=["dice.example.com", "dice.example.com:*"],
+    allowed_origins=["https://dice.example.com"],
+)
+app = server.streamable_http_app(transport_security=security)
 mount_server_card(app, card, path="/mcp/server-card")
 
 card_url = "https://dice.example.com/mcp/server-card"

docs_src/server_cards/tutorial002.py

@@ -26,6 +26,7 @@
 
 def write_static_site(directory: Path) -> None:
     """Write the card and the well-known catalog under `directory`."""
+    directory.mkdir(parents=True, exist_ok=True)
     (directory / "server-card.json").write_text(card_json)
     well_known = directory / ".well-known"
     well_known.mkdir(parents=True, exist_ok=True)

docs_src/server_cards/tutorial004.py

@@ -1,3 +1,5 @@
+from urllib.parse import urljoin
+
 import httpx2
 
 from mcp.client.experimental.ai_catalog import fetch_ai_catalog, well_known_ai_catalog_url
@@ -17,5 +19,7 @@ async def main() -> None:
         for entry in catalog.entries:
             if entry.media_type != MCP_SERVER_CARD_MEDIA_TYPE or entry.url is None:
                 continue
-            card = await fetch_server_card(entry.url, http_client=http_client)
+            # Entry URLs may be relative; resolve them against the catalog's
+            # location, just as `discover_server_cards` does.
+            card = await fetch_server_card(urljoin(catalog_url, entry.url), http_client=http_client)
             print(entry.identifier, "->", card.name)

src/mcp/server/experimental/ai_catalog.py

@@ -37,12 +37,16 @@
 __all__ = ["DISCOVERY_HEADERS", "server_card_entry", "ai_catalog_route", "mount_ai_catalog"]
 
 #: Response headers for discovery endpoints (catalogs and the artifacts they
-#: reference): CORS headers so browser clients can read them, plus a caching
-#: hint.
+#: reference): the CORS headers the discovery spec requires so browser clients
+#: can read them and use conditional GETs, plus a caching hint. ``If-None-Match``
+#: is allowed (and ``ETag`` exposed) so a cross-origin browser can revalidate a
+#: cached card; because ``If-None-Match`` is not a CORS-safelisted request
+#: header, the routes also answer the ``OPTIONS`` preflight it triggers.
 DISCOVERY_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET",
-    "Access-Control-Allow-Headers": "Content-Type",
+    "Access-Control-Allow-Headers": "Content-Type, If-None-Match",
+    "Access-Control-Expose-Headers": "ETag",
     "Cache-Control": "public, max-age=3600",
 }
 
@@ -62,7 +66,16 @@ def _if_none_match_matches(if_none_match: str | None, etag: str) -> bool:
 
 
 def discovery_response(request: Request, body: bytes, media_type: str) -> Response:
-    """Build a cacheable discovery response with conditional ETag handling."""
+    """Build a cacheable discovery response with conditional ETag handling.
+
+    A ``GET`` returns ``body`` with the discovery headers and a strong ``ETag``,
+    or ``304 Not Modified`` when the request's ``If-None-Match`` already matches.
+    An ``OPTIONS`` request is answered as a CORS preflight (``204`` with the
+    discovery headers, no body) so browser clients may send the non-safelisted
+    ``If-None-Match`` header on the follow-up conditional ``GET``.
+    """
+    if request.method == "OPTIONS":
+        return Response(status_code=204, headers=DISCOVERY_HEADERS)
     etag = f'"{hashlib.sha256(body).hexdigest()}"'
     if _if_none_match_matches(request.headers.get("if-none-match"), etag):
         return Response(
@@ -102,18 +115,20 @@ def server_card_entry(card: ServerCard, url: str) -> CatalogEntry:
 
 
 def ai_catalog_route(catalog: AICatalog, *, path: str = AI_CATALOG_WELL_KNOWN_PATH) -> Route:
-    """Build a Starlette GET route that serves ``catalog`` at ``path``.
+    """Build a Starlette route that serves ``catalog`` at ``path``.
 
     Add it to a new app — ``Starlette(routes=[ai_catalog_route(catalog)])`` —
     or an existing one via :func:`mount_ai_catalog`. The payload is serialized
-    once and served with the CORS and caching headers discovery requires.
+    once and served with the CORS and caching headers discovery requires; the
+    route also answers the ``OPTIONS`` CORS preflight browsers send before a
+    cross-origin conditional GET.
     """
     body = catalog.model_dump_json(by_alias=True, exclude_none=True).encode()
 
     async def endpoint(request: Request) -> Response:
         return discovery_response(request, body, AI_CATALOG_MEDIA_TYPE)
 
-    return Route(path, endpoint=endpoint, methods=["GET"], name="ai_catalog")
+    return Route(path, endpoint=endpoint, methods=["GET", "OPTIONS"], name="ai_catalog")
 
 
 def mount_ai_catalog(app: Starlette, catalog: AICatalog, *, path: str = AI_CATALOG_WELL_KNOWN_PATH) -> None:

src/mcp/server/experimental/server_card.py

@@ -41,14 +41,27 @@
 
 
 class _ServerIdentity(Protocol):
-    """The identity attributes shared by the low-level ``Server`` and ``MCPServer``."""
+    """The identity attributes shared by the low-level ``Server`` and ``MCPServer``.
 
-    name: str
-    version: str | None
-    title: str | None
-    description: str | None
-    website_url: str | None
-    icons: list[Icon] | None
+    The members are declared read-only (via ``@property``) so the protocol is
+    satisfied by both the low-level ``Server`` (which stores ``version`` as a
+    plain ``str``) and ``MCPServer`` (which exposes read-only properties). A
+    writable attribute would be invariant and reject ``Server.version: str``
+    against ``version: str | None``.
+    """
+
+    @property
+    def name(self) -> str: ...
+    @property
+    def version(self) -> str | None: ...
+    @property
+    def title(self) -> str | None: ...
+    @property
+    def description(self) -> str | None: ...
+    @property
+    def website_url(self) -> str | None: ...
+    @property
+    def icons(self) -> list[Icon] | None: ...
 
 
 def build_server_card(
@@ -82,7 +95,7 @@ def build_server_card(
         pydantic.ValidationError: If the resulting card is invalid (e.g. ``name``
             is not reverse-DNS).
     """
-    if server.version is None:
+    if not server.version:
         raise ValueError("server.version must be set to build a Server Card")
     if not server.description:
         raise ValueError("server.description must be set to build a Server Card")
@@ -100,22 +113,23 @@ def build_server_card(
 
 
 def server_card_route(card: ServerCard, *, path: str = "/server-card") -> Route:
-    """Build a Starlette GET route that serves ``card`` at ``path``.
+    """Build a Starlette route that serves ``card`` at ``path``.
 
     ``path`` defaults to ``/server-card``, the recommended location
     (``<streamable-http-url>/server-card``). Add the route to
     a new app — ``Starlette(routes=[server_card_route(card)])`` — or an existing
     one via :func:`mount_server_card`, and advertise the resulting URL in an AI
     Catalog entry. The payload is serialized once and served as
     ``application/mcp-server-card+json`` with the CORS and caching headers
-    discovery requires.
+    discovery requires; the route also answers the ``OPTIONS`` CORS preflight
+    browsers send before a cross-origin conditional GET.
     """
     body = card.model_dump_json(by_alias=True, exclude_none=True).encode()
 
     async def endpoint(request: Request) -> Response:
         return discovery_response(request, body, MCP_SERVER_CARD_MEDIA_TYPE)
 
-    return Route(path, endpoint=endpoint, methods=["GET"], name="mcp_server_card")
+    return Route(path, endpoint=endpoint, methods=["GET", "OPTIONS"], name="mcp_server_card")
 
 
 def mount_server_card(app: Starlette, card: ServerCard, *, path: str = "/server-card") -> None:

src/mcp/shared/experimental/ai_catalog/types.py

@@ -180,9 +180,9 @@ class CatalogEntry(MCPModel):
     identifier: str
     """Identifier for the artifact; SHOULD be a URN or URI.
 
-    MCP server entries use ``urn:air:{publisher}:{name}``, where ``publisher`` is
-    the forward-DNS form of the referenced Server Card's namespace and ``name``
-    is its name suffix.
+    MCP server entries use ``urn:air:{publisher}:mcp:{name}``, where ``publisher``
+    is the forward-DNS form of the referenced Server Card's namespace and
+    ``name`` is its name suffix.
     """
 
     display_name: str | None = None

tests/experimental/ai_catalog/test_server.py

@@ -46,6 +46,12 @@ async def _head(app: Starlette, path: str) -> httpx2.Response:
         return await client.head(path)
 
 
+async def _options(app: Starlette, path: str) -> httpx2.Response:
+    transport = httpx2.ASGITransport(app=app)
+    async with httpx2.AsyncClient(transport=transport, base_url="https://dice.example.com") as client:
+        return await client.options(path)
+
+
 async def test_ai_catalog_route_serves_catalog_with_discovery_headers() -> None:
     catalog = AICatalog(spec_version="1.0", entries=[server_card_entry(make_card(), CARD_URL)])
     app = Starlette(routes=[ai_catalog_route(catalog)])
@@ -55,7 +61,8 @@ async def test_ai_catalog_route_serves_catalog_with_discovery_headers() -> None:
     # Discovery requires CORS headers (MUST) and caching headers (SHOULD).
     assert response.headers["access-control-allow-origin"] == "*"
     assert response.headers["access-control-allow-methods"] == "GET"
-    assert response.headers["access-control-allow-headers"] == "Content-Type"
+    assert response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert response.headers["access-control-expose-headers"] == "ETag"
     assert response.headers["cache-control"] == "public, max-age=3600"
     etag = response.headers["etag"]
     assert re.fullmatch(r'"[0-9a-f]{64}"', etag)
@@ -68,7 +75,7 @@ async def test_ai_catalog_route_serves_catalog_with_discovery_headers() -> None:
     assert not_modified.headers["etag"] == etag
     assert not_modified.headers["access-control-allow-origin"] == "*"
     assert not_modified.headers["access-control-allow-methods"] == "GET"
-    assert not_modified.headers["access-control-allow-headers"] == "Content-Type"
+    assert not_modified.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
     assert not_modified.headers["cache-control"] == "public, max-age=3600"
     assert not_modified.content == b""
 
@@ -87,6 +94,20 @@ async def test_ai_catalog_route_serves_catalog_with_discovery_headers() -> None:
     assert non_matching.text == catalog.model_dump_json(by_alias=True, exclude_none=True)
 
 
+async def test_ai_catalog_route_answers_cors_preflight() -> None:
+    """A browser conditional GET sends `If-None-Match`, a non-safelisted header,
+    so it preflights with OPTIONS; the route must answer it with the CORS headers."""
+    catalog = AICatalog(spec_version="1.0", entries=[server_card_entry(make_card(), CARD_URL)])
+    app = Starlette(routes=[ai_catalog_route(catalog)])
+    response = await _options(app, "/.well-known/ai-catalog.json")
+    assert response.status_code == 204
+    assert response.headers["access-control-allow-origin"] == "*"
+    assert response.headers["access-control-allow-methods"] == "GET"
+    assert response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert response.headers["access-control-expose-headers"] == "ETag"
+    assert response.content == b""
+
+
 async def test_mount_ai_catalog_on_existing_app() -> None:
     app = Starlette()
     mount_ai_catalog(app, AICatalog(spec_version="1.0", entries=[]))

tests/experimental/server_card/test_server.py

@@ -48,7 +48,7 @@ def test_build_server_card_from_server_identity() -> None:
 
 
 def test_build_server_card_requires_version() -> None:
-    server = Server("no-version", description="desc")  # version defaults to None
+    server = Server("no-version", description="desc")  # version defaults to ""
     with pytest.raises(ValueError) as excinfo:
         build_server_card(server, name="example/no-version")
     assert str(excinfo.value) == "server.version must be set to build a Server Card"
@@ -73,6 +73,12 @@ async def _head(app: Starlette, path: str) -> httpx2.Response:
         return await client.head(path)
 
 
+async def _options(app: Starlette, path: str) -> httpx2.Response:
+    transport = httpx2.ASGITransport(app=app)
+    async with httpx2.AsyncClient(transport=transport, base_url="https://dice.example.com") as client:
+        return await client.options(path)
+
+
 async def test_server_card_route_serves_card_with_discovery_headers() -> None:
     card = build_server_card(make_server(), name="example/dice")
     app = Starlette(routes=[server_card_route(card, path=CARD_PATH)])
@@ -82,7 +88,8 @@ async def test_server_card_route_serves_card_with_discovery_headers() -> None:
     # Discovery requires CORS headers (MUST) and caching headers (SHOULD).
     assert response.headers["access-control-allow-origin"] == "*"
     assert response.headers["access-control-allow-methods"] == "GET"
-    assert response.headers["access-control-allow-headers"] == "Content-Type"
+    assert response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert response.headers["access-control-expose-headers"] == "ETag"
     assert response.headers["cache-control"] == "public, max-age=3600"
     etag = response.headers["etag"]
     assert re.fullmatch(r'"[0-9a-f]{64}"', etag)
@@ -112,6 +119,20 @@ async def test_server_card_route_serves_card_with_discovery_headers() -> None:
     assert non_matching.text == card.model_dump_json(by_alias=True, exclude_none=True)
 
 
+async def test_server_card_route_answers_cors_preflight() -> None:
+    """A browser conditional GET sends `If-None-Match`, a non-safelisted header,
+    so it preflights with OPTIONS; the route must answer it with the CORS headers."""
+    card = build_server_card(make_server(), name="example/dice")
+    app = Starlette(routes=[server_card_route(card, path=CARD_PATH)])
+    response = await _options(app, CARD_PATH)
+    assert response.status_code == 204
+    assert response.headers["access-control-allow-origin"] == "*"
+    assert response.headers["access-control-allow-methods"] == "GET"
+    assert response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert response.headers["access-control-expose-headers"] == "ETag"
+    assert response.content == b""
+
+
 async def test_mount_server_card_on_existing_app_and_client_fetch() -> None:
     card = build_server_card(
         make_server(),