Support pagination per MCP specification

## Motivation and Context

The MCP specification defines cursor-based pagination for list operations that
may return large result sets:
https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination

Pagination allows servers to yield results in smaller chunks rather than all at once,
which is especially important when connecting to external services over the internet.

The Ruby SDK previously returned complete arrays for all list endpoints
(`tools/list`, `resources/list`, `prompts/list`, `resources/templates/list`)
without pagination support. This adds cursor-based pagination.

### Server-side

A new `MCP::Server::Pagination` module is introduced (mixed into `MCP::Server`)
that provides the `paginate` helper for slicing a collection by cursor and
a `cursor_from` helper that extracts the cursor from the request params
while rejecting non-Hash inputs with `-32602 Invalid params` per the specification.

`MCP::Server.new` accepts a new `page_size:` keyword argument.
When `nil` (the default), all items are returned in a single response,
preserving the existing behavior. When set to a positive integer,
list responses include a `nextCursor` field if more pages are available.

`Server#page_size=` is a validating setter that rejects anything other than
`nil` or a positive `Integer`, raising `ArgumentError` on invalid inputs.
The constructor routes through the setter, so both `Server.new(page_size: 0)`
and `server.page_size = -1` raise.

Cursors are string tokens carrying a zero-based offset, treated as opaque by
clients. Cursor inputs are validated to be strings per the MCP spec;
invalid cursors (non-string, non-numeric, negative, or out-of-range) raise
`RequestHandlerError` with error code `-32602 (Invalid params)` per the spec.

### Client-side: two complementary APIs

The SDK exposes two API shapes for listing, each serving a different use case:

1. **Single-page with cursor** (`client.list_tools(cursor:)`,
   `list_resources`, `list_resource_templates`, `list_prompts`): each call issues
   one JSON-RPC request and returns a result object (`MCP::Client::ListToolsResult` etc.)
   carrying the page items and an optional `next_cursor`.
   These methods match the single-page-with-cursor convention used by the Python SDK
   (`session.list_tools(params=PaginatedRequestParams(cursor=...))`)
   and the TypeScript SDK (`client.listTools({ cursor })`). The method name and
   the `cursor` parameter name are identical across the three SDKs,
   so pagination code translates directly between languages.

2. **Whole-collection** (`client.tools`, `client.resources`, `client.resource_templates`,
   `client.prompts`): auto-iterates through all pages and returns a plain array of items,
   guaranteeing the full collection regardless of the server's `page_size` setting.
   The auto-pagination loop tracks previously seen cursors in a set and exits if the server
   revisits any of them, guarding against both immediate repeats and multi-cursor cycles
   (e.g. `A -> B -> A`). This mirrors Rust SDK's `list_all_*` convenience methods,
   though the Ruby names are preserved from the pre-pagination 0.13.0 API for backward compatibility.
   Future rename to `list_all_*` is left as a TODO in the source.

Result classes are `Struct`s named to mirror Python SDK's `ListToolsResult` /
`ListPromptsResult` / etc. to align naming with other SDKs. Each struct exposes
its page items (e.g. `result.tools`), an optional `next_cursor` for continuation,
and an optional `meta` field mirroring the MCP `Result` type's `_meta` response field
so servers that decorate list responses do not lose metadata through the client.

### Ruby-specific ergonomics

`Server.new(page_size:)` and the `Pagination` module are Ruby-specific.
The Python and TypeScript SDKs do not expose a built-in `page_size` helper;
developers there re-implement cursor slicing inside each handler.
In Ruby, setting `page_size:` on the server is enough for the SDK to handle
the slicing across the four built-in list endpoints.

### README

A Pagination section documents both the server-side `page_size:` option and
the client-side iteration patterns, including an explicit note that each `list_*` call
is a single JSON-RPC round trip whose response size depends on the server's `page_size`,
and that `client.tools` / `.resources` / `.resource_templates` / `.prompts` return
the complete collection when needed.

## How Has This Been Tested?

- Added tests for the `Pagination` module (`test/mcp/server/pagination_test.rb`),
  server-side pagination (`test/mcp/server_test.rb`), and client-side pagination
  (`test/mcp/client_test.rb`).
- Added and existing tests pass. `rake rubocop` is clean and `rake conformance` passes.

## Breaking Changes

None. This is a new feature addition. Existing code continues to work unchanged:
`page_size` defaults to `nil` on the server (returns all items, no `nextCursor`),
and the client's existing `tools` / `resources` / `resource_templates` / `prompts` methods
continue to return complete arrays by transparently iterating through pages.

README.md

@@ -40,6 +40,7 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports notifications for list changes (tools, prompts, resources)
 - Supports roots (server-to-client filesystem boundary queries)
 - Supports sampling (server-to-client LLM completion requests)
+- Supports cursor-based pagination for list operations
 
 ### Supported Methods
 
@@ -1365,6 +1366,90 @@ When configured, sessions that receive no HTTP requests for this duration are au
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
 ```
 
+### Pagination
+
+The MCP Ruby SDK supports [pagination](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)
+for list operations that may return large result sets. Pagination uses string cursor tokens carrying a zero-based offset,
+treated as opaque by clients: the server decides page size, and the client follows `nextCursor` until the server omits it.
+
+Pagination applies to `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list`.
+
+#### Server-Side: Enabling Pagination
+
+Pass `page_size:` to `MCP::Server.new` to split list responses into pages. When `page_size` is omitted (the default),
+list responses contain all items in a single response, preserving the pre-pagination behavior.
+
+```ruby
+server = MCP::Server.new(
+  name: "my_server",
+  tools: tools,
+  page_size: 50,
+)
+```
+
+When `page_size` is set, list responses include a `nextCursor` field whenever more pages are available:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "tools": [
+      { "name": "example_tool" }
+    ],
+    "nextCursor": "50"
+  }
+}
+```
+
+Invalid cursors (e.g. non-numeric, negative, or out-of-range) are rejected with JSON-RPC error code `-32602 (Invalid params)` per the MCP specification.
+
+#### Client-Side: Iterating Pages
+
+`MCP::Client` exposes `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
+**Each call issues exactly one `*/list` JSON-RPC request and returns exactly one page** — not the full collection.
+The returned result object (`MCP::Client::ListToolsResult` etc.) exposes the page items and the next cursor as method accessors:
+
+```ruby
+client = MCP::Client.new(transport: transport)
+
+cursor = nil
+loop do
+  page = client.list_tools(cursor: cursor)
+  page.tools.each { |tool| process(tool) }
+  cursor = page.next_cursor
+  break unless cursor
+end
+```
+
+The same pattern applies to `list_prompts` (`page.prompts`), `list_resources` (`page.resources`), and
+`list_resource_templates` (`page.resource_templates`). `next_cursor` is `nil` on the final page.
+
+Because a single call returns a single page, how many items come back depends on the server's `page_size` configuration:
+
+| Server `page_size` | `client.list_tools(cursor: nil)`                                    |
+|--------------------|---------------------------------------------------------------------|
+| Not set (default)  | Returns every item in one response. `next_cursor` is `nil`.         |
+| Set to `N`         | Returns the first `N` items. `next_cursor` is set for continuation. |
+
+If your application needs the complete collection regardless of how the server is configured, either loop on
+`next_cursor` as shown above, or use the whole-collection methods described below.
+
+#### Fetching the Complete Collection
+
+`client.tools`, `client.resources`, `client.resource_templates`, and `client.prompts` auto-iterate
+through all pages and return a plain array of items, guaranteeing the full collection regardless
+of the server's `page_size` setting. When a server paginates, they issue multiple JSON-RPC round
+trips per call and break out of the pagination loop if the server returns the same `nextCursor`
+twice in a row as a safety measure.
+
+```ruby
+tools = client.tools # => Array<MCP::Client::Tool> of every tool on the server.
+```
+
+Use these when you want the complete list; use `list_tools(cursor:)` etc. when you need
+fine-grained iteration (e.g. to stream-process pages without loading everything into memory).
+
 ### Advanced
 
 #### Custom Methods