Move CacheableMethod to mcp_types.methods and derive CACHEABLE_METHODS from the method registry

Author: maxisbey

src/mcp-types/mcp_types/methods.py

@@ -13,7 +13,7 @@
 from collections.abc import Mapping
 from functools import cache
 from types import MappingProxyType, UnionType
-from typing import Any, Final, TypeVar
+from typing import Any, Final, Literal, TypeVar, get_args
 
 from pydantic import BaseModel, TypeAdapter
 
@@ -23,9 +23,11 @@
 from mcp_types.version import KNOWN_PROTOCOL_VERSIONS
 
 __all__ = [
+    "CACHEABLE_METHODS",
     "CLIENT_NOTIFICATIONS",
     "CLIENT_REQUESTS",
     "CLIENT_RESULTS",
+    "CacheableMethod",
     "MONOLITH_NOTIFICATIONS",
     "MONOLITH_REQUESTS",
     "MONOLITH_RESULTS",
@@ -404,6 +406,29 @@
 """Monolith result model (or two-arm union) per request method."""
 
 
+# --- Cacheable methods ---
+
+CacheableMethod = Literal[
+    "prompts/list",
+    "resources/list",
+    "resources/read",
+    "resources/templates/list",
+    "server/discover",
+    "tools/list",
+]
+"""The methods whose results carry `ttlMs`/`cacheScope`. Closed set: the spec
+defines caching hints on exactly these six. Hand-written because a Literal
+cannot be computed at runtime; tests weld it to `CACHEABLE_METHODS`."""
+
+CACHEABLE_METHODS: Final[frozenset[str]] = frozenset(
+    method
+    for method, row in MONOLITH_RESULTS.items()
+    if any(issubclass(arm, types.CacheableResult) for arm in (get_args(row) if isinstance(row, UnionType) else (row,)))
+)
+"""Runtime mirror of `CacheableMethod`, derived from `MONOLITH_RESULTS`: a
+method is cacheable iff its result row has a `CacheableResult` arm."""
+
+
 # --- Parse functions ---
 
 # Envelope stubs merged into bodies for surface validation (surface classes are full frames).

src/mcp/server/caching.py

@@ -11,27 +11,13 @@
 
 from collections.abc import Mapping
 from dataclasses import dataclass
-from typing import Any, Final, Literal, TypeVar, get_args
+from typing import Any, Literal, TypeVar
 
 import mcp_types as types
+from mcp_types.methods import CACHEABLE_METHODS, CacheableMethod
 
 __all__ = ["CACHEABLE_METHODS", "CacheHint", "CacheableMethod", "apply_cache_hint", "validate_cache_hints"]
 
-CacheableMethod = Literal[
-    "prompts/list",
-    "resources/list",
-    "resources/read",
-    "resources/templates/list",
-    "server/discover",
-    "tools/list",
-]
-"""The methods whose results carry `ttlMs`/`cacheScope`. Closed set: the spec
-defines caching hints on exactly these six (tests pin it to which result models
-mix in `CacheableResult`)."""
-
-CACHEABLE_METHODS: Final[frozenset[str]] = frozenset(get_args(CacheableMethod))
-"""Runtime mirror of `CacheableMethod`, for callers the type checker can't see."""
-
 
 @dataclass(frozen=True, slots=True)
 class CacheHint:

tests/server/test_caching.py

@@ -1,40 +1,25 @@
 """`mcp.server.caching`: `CacheHint` validation, per-field fills, and the
 `cache_hints` constructor map reaching the wire on both server tiers."""
 
-from types import UnionType
-from typing import Any, cast, get_args
+from typing import Any, cast
 
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import (
-    CacheableResult,
     ListResourcesResult,
     ListToolsResult,
     PaginatedRequestParams,
     Resource,
     Tool,
-    methods,
 )
 
 from mcp import Client
 from mcp.server import CacheHint, MCPServer, Server, ServerRequestContext
-from mcp.server.caching import CACHEABLE_METHODS, apply_cache_hint
+from mcp.server.caching import apply_cache_hint
 
 pytestmark = pytest.mark.anyio
 
 
-def test_cacheable_methods_match_the_result_models() -> None:
-    """Spec-mandated set (SEP-2549): `CACHEABLE_METHODS` mirrors exactly the
-    methods whose monolith result models mix in `CacheableResult` - if the
-    schema gains or loses a cacheable result, this weld breaks."""
-    derived: set[str] = set()
-    for method, model in methods.MONOLITH_RESULTS.items():
-        arms = get_args(model) if isinstance(model, UnionType) else (model,)
-        if any(isinstance(arm, type) and issubclass(arm, CacheableResult) for arm in arms):
-            derived.add(method)
-    assert CACHEABLE_METHODS == derived
-
-
 def test_cache_hint_defaults_match_the_conservative_model_defaults() -> None:
     """SDK-defined: an unconfigured hint fills the same values the result models
     already default to - immediately stale, not shared - so stamping it is

tests/types/test_methods.py

@@ -548,6 +548,14 @@ def test_built_in_maps_are_immutable():
             _assign_item(built_in)
 
 
+def test_cacheable_methods_mirror_the_cacheable_method_literal():
+    """Spec-mandated set (SEP-2549): the hand-written `CacheableMethod` Literal and
+    `CACHEABLE_METHODS` (derived from which `MONOLITH_RESULTS` rows have a
+    `CacheableResult` arm) name the same methods - if the schema gains or loses a
+    cacheable result, this weld breaks."""
+    assert methods.CACHEABLE_METHODS == frozenset(get_args(methods.CacheableMethod))
+
+
 def test_minimal_request_bodies_parse_through_every_request_row():
     for (method, version), surface_type in methods.CLIENT_REQUESTS.items():
         parsed = methods.parse_client_request(method, version, REQUEST_PARAMS_FIXTURES[surface_type])