|
| 1 | +"""Era-aware capability derivation in `Server.get_capabilities`. |
| 2 | +
|
| 3 | +Without `protocol_version` (or at a handshake version), derivation is the |
| 4 | +legacy one: `resources.subscribe` mirrors the `resources/subscribe` handler |
| 5 | +registry and the `listChanged` flags come from `NotificationOptions`. At any |
| 6 | +other version -- modern, or an unknown future string (fail-closed) -- the four |
| 7 | +subscription-delivered bits derive solely from whether a |
| 8 | +`subscriptions/listen` handler is registered, gated on family presence -- so |
| 9 | +the server never advertises a subscription bit on a wire that answers |
| 10 | +`subscriptions/listen` with METHOD_NOT_FOUND (the SEP-2575 conformance gate). |
| 11 | +""" |
| 12 | + |
| 13 | +from typing import Any |
| 14 | + |
| 15 | +import mcp_types as types |
| 16 | +from mcp_types.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION |
| 17 | + |
| 18 | +from mcp.server import NotificationOptions, Server, ServerRequestContext |
| 19 | + |
| 20 | + |
| 21 | +async def _list_tools( |
| 22 | + ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None |
| 23 | +) -> types.ListToolsResult: |
| 24 | + raise NotImplementedError |
| 25 | + |
| 26 | + |
| 27 | +async def _list_prompts( |
| 28 | + ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None |
| 29 | +) -> types.ListPromptsResult: |
| 30 | + raise NotImplementedError |
| 31 | + |
| 32 | + |
| 33 | +async def _list_resources( |
| 34 | + ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None |
| 35 | +) -> types.ListResourcesResult: |
| 36 | + raise NotImplementedError |
| 37 | + |
| 38 | + |
| 39 | +async def _subscribe(ctx: ServerRequestContext[Any], params: types.SubscribeRequestParams) -> types.EmptyResult: |
| 40 | + raise NotImplementedError |
| 41 | + |
| 42 | + |
| 43 | +async def _unsubscribe(ctx: ServerRequestContext[Any], params: types.UnsubscribeRequestParams) -> types.EmptyResult: |
| 44 | + raise NotImplementedError |
| 45 | + |
| 46 | + |
| 47 | +async def _listen( |
| 48 | + ctx: ServerRequestContext[Any], params: types.SubscriptionsListenRequestParams |
| 49 | +) -> types.SubscriptionsListenResult: |
| 50 | + raise NotImplementedError |
| 51 | + |
| 52 | + |
| 53 | +def dual_era_server() -> Server[Any]: |
| 54 | + """All three families plus the legacy `resources/subscribe` pair, no listen |
| 55 | + handler -- the era-blind derivation shape: legacy subscribe handlers must |
| 56 | + not be advertised on a wire that rejects `subscriptions/listen`.""" |
| 57 | + return Server( |
| 58 | + "dual-era", |
| 59 | + on_list_tools=_list_tools, |
| 60 | + on_list_prompts=_list_prompts, |
| 61 | + on_list_resources=_list_resources, |
| 62 | + on_subscribe_resource=_subscribe, |
| 63 | + on_unsubscribe_resource=_unsubscribe, |
| 64 | + ) |
| 65 | + |
| 66 | + |
| 67 | +def test_legacy_derivation_unchanged_without_protocol_version() -> None: |
| 68 | + """SDK-defined regression pin: with no `protocol_version`, derivation is |
| 69 | + exactly the pre-era-aware one -- `subscribe` from the legacy handler |
| 70 | + registry, `listChanged` flags from `NotificationOptions`.""" |
| 71 | + capabilities = dual_era_server().get_capabilities( |
| 72 | + NotificationOptions(prompts_changed=True, resources_changed=True, tools_changed=True) |
| 73 | + ) |
| 74 | + assert capabilities == types.ServerCapabilities( |
| 75 | + prompts=types.PromptsCapability(list_changed=True), |
| 76 | + resources=types.ResourcesCapability(subscribe=True, list_changed=True), |
| 77 | + tools=types.ToolsCapability(list_changed=True), |
| 78 | + ) |
| 79 | + |
| 80 | + |
| 81 | +def test_modern_version_never_derives_bits_from_legacy_subscribe_or_notification_options() -> None: |
| 82 | + """Spec-mandated (SEP-2575 advertised-iff-served): at a modern version a |
| 83 | + server without a `subscriptions/listen` handler advertises no subscription |
| 84 | + bit, even with legacy `resources/subscribe` handlers registered and every |
| 85 | + `NotificationOptions` flag set -- legacy subscribe handlers must not be |
| 86 | + advertised on a wire that rejects `subscriptions/listen`.""" |
| 87 | + capabilities = dual_era_server().get_capabilities( |
| 88 | + NotificationOptions(prompts_changed=True, resources_changed=True, tools_changed=True), |
| 89 | + protocol_version=LATEST_MODERN_VERSION, |
| 90 | + ) |
| 91 | + assert capabilities == types.ServerCapabilities( |
| 92 | + prompts=types.PromptsCapability(list_changed=False), |
| 93 | + resources=types.ResourcesCapability(subscribe=False, list_changed=False), |
| 94 | + tools=types.ToolsCapability(list_changed=False), |
| 95 | + ) |
| 96 | + |
| 97 | + |
| 98 | +def test_unknown_future_version_derives_fail_closed_like_modern() -> None: |
| 99 | + """SDK-defined fail-closed posture: an unrecognized (future) protocol |
| 100 | + version uses the modern derivation -- bits from `subscriptions/listen` |
| 101 | + registration only, never the legacy registries -- so a newer wire is never |
| 102 | + promised a bit this server cannot serve on it.""" |
| 103 | + capabilities = dual_era_server().get_capabilities( |
| 104 | + NotificationOptions(prompts_changed=True, resources_changed=True, tools_changed=True), |
| 105 | + protocol_version="2199-01-01", |
| 106 | + ) |
| 107 | + assert capabilities == types.ServerCapabilities( |
| 108 | + prompts=types.PromptsCapability(list_changed=False), |
| 109 | + resources=types.ResourcesCapability(subscribe=False, list_changed=False), |
| 110 | + tools=types.ToolsCapability(list_changed=False), |
| 111 | + ) |
| 112 | + |
| 113 | + |
| 114 | +def test_modern_version_advertises_all_bits_when_listen_is_wired() -> None: |
| 115 | + """SDK-defined: at a modern version a registered `subscriptions/listen` |
| 116 | + handler turns on all four subscription bits, independent of |
| 117 | + `NotificationOptions` (left at its all-False default).""" |
| 118 | + server = Server( |
| 119 | + "listen-wired", |
| 120 | + on_list_tools=_list_tools, |
| 121 | + on_list_prompts=_list_prompts, |
| 122 | + on_list_resources=_list_resources, |
| 123 | + on_subscriptions_listen=_listen, |
| 124 | + ) |
| 125 | + capabilities = server.get_capabilities(protocol_version=LATEST_MODERN_VERSION) |
| 126 | + assert capabilities == types.ServerCapabilities( |
| 127 | + prompts=types.PromptsCapability(list_changed=True), |
| 128 | + resources=types.ResourcesCapability(subscribe=True, list_changed=True), |
| 129 | + tools=types.ToolsCapability(list_changed=True), |
| 130 | + ) |
| 131 | + |
| 132 | + |
| 133 | +def test_modern_version_gates_bits_on_family_presence() -> None: |
| 134 | + """SDK-defined: listen-wiredness only surfaces per family -- a server with |
| 135 | + no `prompts/list` handler advertises no prompts capability at all, while |
| 136 | + the families it does serve carry the bits.""" |
| 137 | + server = Server( |
| 138 | + "no-prompts", |
| 139 | + on_list_tools=_list_tools, |
| 140 | + on_list_resources=_list_resources, |
| 141 | + on_subscriptions_listen=_listen, |
| 142 | + ) |
| 143 | + capabilities = server.get_capabilities(protocol_version=LATEST_MODERN_VERSION) |
| 144 | + assert capabilities == types.ServerCapabilities( |
| 145 | + resources=types.ResourcesCapability(subscribe=True, list_changed=True), |
| 146 | + tools=types.ToolsCapability(list_changed=True), |
| 147 | + ) |
| 148 | + |
| 149 | + |
| 150 | +def test_handshake_version_uses_legacy_derivation() -> None: |
| 151 | + """SDK-defined: passing a handshake version explicitly means the legacy |
| 152 | + derivation -- the kwarg carries the connection's negotiated version, and |
| 153 | + handshake wires keep the 2025 meaning of the bits.""" |
| 154 | + options = NotificationOptions(prompts_changed=True) |
| 155 | + server = dual_era_server() |
| 156 | + assert server.get_capabilities(options, protocol_version=LATEST_HANDSHAKE_VERSION) == server.get_capabilities( |
| 157 | + options |
| 158 | + ) |
0 commit comments