Support resource subscriptions per MCP specification

[koic]

Motivation and Context

The MCP specification defines resources/subscribe, resources/unsubscribe, and notifications/resources/updated for clients to monitor resource changes: https://modelcontextprotocol.io/specification/2025-03-26/server/resources#subscriptions

The Ruby SDK had stub (no-op) handlers but provided no way for server developers to customize subscription behavior or send update notifications.

Following the Python SDK approach, the SDK does not track subscription state internally. Server developers register handler blocks and manage their own subscription state, allowing flexibility for different subscription semantics (per-session tracking, persistence, debouncing, etc.).

Three methods are added:

• Server#resources_subscribe_handler: registers a handler for resources/subscribe requests
• Server#resources_unsubscribe_handler: registers a handler for resources/unsubscribe requests
• ServerSession#notify_resources_updated: sends a notifications/resources/updated notification to the subscribing client

ServerContext#notify_resources_updated is also added so that tool handlers can send the notification scoped to the originating session.

How Has This Been Tested?

All tests pass (rake test), RuboCop is clean. New tests cover custom handler registration for resources/subscribe and resources/unsubscribe, session-scoped notify_resources_updated notifications, error handling, and ServerContext delegation.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[jonathanhefner]

Vibe-reviewed. Claude says: "This is a well-structured, spec-compliant addition that follows the existing codebase patterns. The only discussion-worthy point is #1 (the related_request_id omission). Everything else is clean."

(Claude pointed out that every other session-scoped notification method in ServerSession accepts and passes related_request_id. However, I think the omission for resource update notifications is correct, right?)

[koic]

Good catch. The omission is intentional.

related_request_id is used by StreamableHTTPTransport to route notifications to the POST response stream of an in-flight request, which fits request-scoped events like notify_progress and notify_log_message.

notifications/resources/updated, on the other hand, is not tied to a specific request but represents an asynchronous state change on the server. Omitting related_request_id allows it to be delivered via the session’s SSE stream.

This is consistent with notify_elicitation_complete, which follows the same pattern.