wehub-resource-sync
49b9bb6724
Deploy Docs / deploy-docs (push) Failing after 1s
Conformance Tests / client-conformance (push) Failing after 3s
Conformance Tests / server-conformance (push) Failing after 1s
GitHub Actions Security Analysis / zizmor (push) Failing after 1s
CI / checks (push) Failing after 59m20s
CI / all-green (push) Has been cancelled
244 lines
11 KiB
Python
244 lines
11 KiB
Python
"""`mcp.server.caching`: `CacheHint` validation, per-field fills, and the
|
|
`cache_hints` constructor map reaching the wire on both server tiers."""
|
|
|
|
from typing import Any, cast
|
|
|
|
import pytest
|
|
from inline_snapshot import snapshot
|
|
from mcp_types import (
|
|
InputRequiredResult,
|
|
ListResourcesResult,
|
|
ListToolsResult,
|
|
PaginatedRequestParams,
|
|
ReadResourceRequestParams,
|
|
Resource,
|
|
Tool,
|
|
)
|
|
|
|
from mcp import Client
|
|
from mcp.server import CacheHint, MCPServer, Server, ServerRequestContext
|
|
from mcp.server.caching import apply_cache_hint
|
|
|
|
pytestmark = pytest.mark.anyio
|
|
|
|
|
|
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
|
|
indistinguishable from not stamping at all."""
|
|
hint = CacheHint()
|
|
model = ListToolsResult(tools=[])
|
|
assert (hint.ttl_ms, hint.scope) == (model.ttl_ms, model.cache_scope)
|
|
|
|
|
|
def test_a_negative_ttl_is_rejected_at_hint_construction() -> None:
|
|
"""Spec-mandated: servers MUST provide `ttlMs >= 0`, so a negative value
|
|
fails at `CacheHint` construction rather than reaching the wire."""
|
|
with pytest.raises(ValueError) as exc:
|
|
CacheHint(ttl_ms=-1)
|
|
assert str(exc.value) == snapshot("ttl_ms must be >= 0, got -1")
|
|
|
|
|
|
def test_an_unknown_scope_is_rejected_at_hint_construction() -> None:
|
|
"""Spec-mandated: `cacheScope` is a closed enum, enforced for untyped callers
|
|
the type checker cannot see."""
|
|
with pytest.raises(ValueError) as exc:
|
|
CacheHint(scope=cast(Any, "shared"))
|
|
assert str(exc.value) == snapshot("scope must be 'public' or 'private', got 'shared'")
|
|
|
|
|
|
def test_apply_cache_hint_fills_only_the_fields_the_handler_left_unset() -> None:
|
|
"""SDK-defined precedence, per field: the handler's explicit `ttl_ms` stays,
|
|
the unset `cache_scope` takes the hint's value."""
|
|
result = ListToolsResult(tools=[], ttl_ms=10)
|
|
filled = apply_cache_hint(result, CacheHint(ttl_ms=60_000, scope="public"))
|
|
assert filled.ttl_ms == 10
|
|
assert filled.cache_scope == "public"
|
|
|
|
|
|
def test_apply_cache_hint_never_overrides_explicit_fields_even_at_default_values() -> None:
|
|
"""SDK-defined: an explicit `ttl_ms=0, cache_scope="private"` is a handler
|
|
decision, not an absence - the hint must not replace it (`model_fields_set`
|
|
distinguishes the two)."""
|
|
result = ListToolsResult(tools=[], ttl_ms=0, cache_scope="private")
|
|
assert apply_cache_hint(result, CacheHint(ttl_ms=60_000, scope="public")) is result
|
|
|
|
|
|
def test_a_non_cacheable_method_in_cache_hints_is_rejected_at_server_construction() -> None:
|
|
"""SDK-defined: only the six cacheable methods take hints; a typo or a
|
|
non-cacheable method fails at `Server(...)` time, not silently at runtime."""
|
|
with pytest.raises(ValueError) as exc:
|
|
Server("srv", cache_hints=cast(Any, {"tools/call": CacheHint()}))
|
|
assert str(exc.value) == snapshot(
|
|
"cache_hints keys must be cacheable methods (see CacheableMethod); got: 'tools/call'"
|
|
)
|
|
|
|
|
|
def test_a_non_cache_hint_value_is_rejected_at_server_construction() -> None:
|
|
"""SDK-defined: a config-shaped value (a plain dict instead of a `CacheHint`)
|
|
fails at `Server(...)` time too - not with an `AttributeError` on the first
|
|
request to that method."""
|
|
with pytest.raises(TypeError) as exc:
|
|
Server("srv", cache_hints=cast(Any, {"tools/list": {"ttl_ms": 60_000}}))
|
|
assert str(exc.value) == snapshot("cache_hints['tools/list'] must be a CacheHint, got dict")
|
|
|
|
|
|
def test_a_non_string_cache_hints_key_is_rejected_with_the_unknown_key_error() -> None:
|
|
"""A non-string key takes the same unknown-key ValueError as a typo, not a TypeError from message formatting."""
|
|
with pytest.raises(ValueError) as exc:
|
|
Server("srv", cache_hints=cast(Any, {42: CacheHint()}))
|
|
assert str(exc.value) == snapshot("cache_hints keys must be cacheable methods (see CacheableMethod); got: 42")
|
|
|
|
|
|
async def test_a_dict_returning_handler_takes_the_configured_hint() -> None:
|
|
"""The stamp covers raw-dict results too - 2026-07-28 requires both fields on the wire."""
|
|
hint = CacheHint(ttl_ms=60_000, scope="public")
|
|
|
|
async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams) -> dict[str, Any]:
|
|
return {"tools": [], "resultType": "complete"}
|
|
|
|
server = Server("srv", cache_hints={"tools/list": hint})
|
|
server.add_request_handler("tools/list", PaginatedRequestParams, list_tools)
|
|
async with Client(server) as client:
|
|
result = await client.list_tools()
|
|
assert result.ttl_ms == hint.ttl_ms
|
|
assert result.cache_scope == hint.scope
|
|
|
|
|
|
async def test_a_dict_provided_ttl_wins_and_the_hint_fills_only_the_missing_scope() -> None:
|
|
"""Dict path mirrors the model path's `model_fields_set` precedence: present wire keys win."""
|
|
|
|
async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams) -> dict[str, Any]:
|
|
return {"tools": [], "resultType": "complete", "ttlMs": 25}
|
|
|
|
server = Server("srv", cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")})
|
|
server.add_request_handler("tools/list", PaginatedRequestParams, list_tools)
|
|
async with Client(server) as client:
|
|
result = await client.list_tools()
|
|
assert result.ttl_ms == 25
|
|
assert result.cache_scope == "public"
|
|
|
|
|
|
async def test_a_dict_returning_handler_leaks_no_hint_fields_to_a_2025_session() -> None:
|
|
"""The stamp runs version-independently; the 2025 serialize sieve strips the fields."""
|
|
|
|
async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams) -> dict[str, Any]:
|
|
return {"tools": []}
|
|
|
|
server = Server("srv", cache_hints={"tools/list": CacheHint(ttl_ms=60_000, scope="public")})
|
|
server.add_request_handler("tools/list", PaginatedRequestParams, list_tools)
|
|
async with Client(server, mode="legacy") as client:
|
|
result = await client.list_tools()
|
|
assert "ttl_ms" not in result.model_fields_set
|
|
assert "cache_scope" not in result.model_fields_set
|
|
|
|
|
|
async def test_an_input_required_shaped_dict_is_never_stamped() -> None:
|
|
"""Spec carve-out: interim `input_required` results carry no cache hints, even on a hinted method."""
|
|
|
|
async def read_resource(ctx: ServerRequestContext[Any], params: ReadResourceRequestParams) -> dict[str, Any]:
|
|
return {"resultType": "input_required", "requestState": "s1"}
|
|
|
|
server = Server("srv", cache_hints={"resources/read": CacheHint(ttl_ms=60_000, scope="public")})
|
|
server.add_request_handler("resources/read", ReadResourceRequestParams, read_resource)
|
|
async with Client(server) as client:
|
|
result = await client.session.read_resource("res://x", allow_input_required=True)
|
|
assert isinstance(result, InputRequiredResult)
|
|
assert result.model_dump(by_alias=True, exclude_none=True) == snapshot(
|
|
{"resultType": "input_required", "requestState": "s1"}
|
|
)
|
|
|
|
|
|
async def test_server_cache_hints_reach_the_wire_for_a_bare_handler_result() -> None:
|
|
"""SDK-defined: a lowlevel handler that never thinks about caching emits the
|
|
server-wide hint configured at construction."""
|
|
hint = CacheHint(ttl_ms=60_000, scope="public")
|
|
|
|
async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None) -> ListToolsResult:
|
|
return ListToolsResult(tools=[Tool(name="t", input_schema={"type": "object"})])
|
|
|
|
server = Server("srv", on_list_tools=list_tools, cache_hints={"tools/list": hint})
|
|
async with Client(server) as client:
|
|
result = await client.list_tools()
|
|
assert result.ttl_ms == hint.ttl_ms
|
|
assert result.cache_scope == hint.scope
|
|
|
|
|
|
async def test_every_page_of_a_paginated_list_carries_the_configured_scope() -> None:
|
|
"""Spec-mandated: the same `cacheScope` MUST apply to all pages of one list.
|
|
The map is keyed by method, not cursor, so a handler that leaves scope unset
|
|
gets the same scope on every page. (A handler that overrides the scope owns
|
|
that consistency itself - see `docs/client/caching.md`.)"""
|
|
names = [f"r-{n}" for n in range(4)]
|
|
|
|
async def list_resources(
|
|
ctx: ServerRequestContext[Any], params: PaginatedRequestParams | None
|
|
) -> ListResourcesResult:
|
|
start = 0 if params is None or params.cursor is None else int(params.cursor)
|
|
page = [Resource(uri=f"res://{name}", name=name) for name in names[start : start + 2]]
|
|
next_cursor = str(start + 2) if start + 2 < len(names) else None
|
|
return ListResourcesResult(resources=page, next_cursor=next_cursor)
|
|
|
|
server = Server(
|
|
"srv",
|
|
on_list_resources=list_resources,
|
|
cache_hints={"resources/list": CacheHint(ttl_ms=30_000, scope="public")},
|
|
)
|
|
async with Client(server) as client:
|
|
first = await client.list_resources()
|
|
assert first.next_cursor is not None
|
|
second = await client.list_resources(cursor=first.next_cursor)
|
|
assert (first.cache_scope, second.cache_scope) == ("public", "public")
|
|
assert (first.ttl_ms, second.ttl_ms) == (30_000, 30_000)
|
|
|
|
|
|
async def test_the_default_discover_handler_takes_the_server_discover_hint() -> None:
|
|
"""SDK-defined: the auto-derived `server/discover` result is stamped from the
|
|
map like any other cacheable result - no separate discover-specific knob."""
|
|
server = Server("srv", cache_hints={"server/discover": CacheHint(ttl_ms=300_000, scope="public")})
|
|
async with Client(server) as client:
|
|
discovered = await client.session.discover()
|
|
assert discovered.ttl_ms == 300_000
|
|
assert discovered.cache_scope == "public"
|
|
|
|
|
|
async def test_mcpserver_cache_hints_cover_every_high_level_handler() -> None:
|
|
"""SDK-defined: the `MCPServer` constructor map reaches all six cacheable
|
|
methods. Each method gets a distinct `ttl_ms` so a failure names the handler
|
|
that lost its hint."""
|
|
mcp = MCPServer(
|
|
"demo",
|
|
cache_hints={
|
|
"tools/list": CacheHint(ttl_ms=1_000, scope="public"),
|
|
"resources/list": CacheHint(ttl_ms=2_000, scope="public"),
|
|
"resources/templates/list": CacheHint(ttl_ms=3_000, scope="public"),
|
|
"prompts/list": CacheHint(ttl_ms=4_000, scope="public"),
|
|
"resources/read": CacheHint(ttl_ms=5_000, scope="public"),
|
|
"server/discover": CacheHint(ttl_ms=6_000, scope="public"),
|
|
},
|
|
)
|
|
|
|
@mcp.tool()
|
|
def add(a: int, b: int) -> int:
|
|
raise NotImplementedError
|
|
|
|
@mcp.resource("config://app")
|
|
def config() -> str:
|
|
return "cfg"
|
|
|
|
@mcp.resource("greeting://{name}")
|
|
def greeting(name: str) -> str:
|
|
raise NotImplementedError
|
|
|
|
@mcp.prompt()
|
|
def hello() -> str:
|
|
raise NotImplementedError
|
|
|
|
async with Client(mcp) as client:
|
|
assert (await client.list_tools()).ttl_ms == 1_000
|
|
assert (await client.list_resources()).ttl_ms == 2_000
|
|
assert (await client.list_resource_templates()).ttl_ms == 3_000
|
|
assert (await client.list_prompts()).ttl_ms == 4_000
|
|
assert (await client.read_resource("config://app")).ttl_ms == 5_000
|
|
assert (await client.session.discover()).ttl_ms == 6_000
|