Add support for pagination on list requests (#55)

10 - Added the list resources handler with test class

10 - Update the ListPromptsHandler to use annotations

10 - Add the list resource handler, and it's test as well

10 - Added the registry logic

10 - Added the list tools handler logic

10 - Fix all php-cs-fixer related issues

10 - Resolved phpstan issues for ListPromptsHandlerTest

10 - Resolved phpstan issues for ListToolsHandlerTest

10 - Resolved phpstan issues for ListResourcesHandlerTest

10 - Resolved phpstan issues in registry class

10 - Resolved phpstan issues for the handler class

10 - Resolved php cs fixer issues

10 - Resolved all phpstan issues by generating the baseline again

10 - Remove the two loop operation and use foreach for optimization

10 - Removed unused code and resolved namespace

10 - Add signatures to interface and registry

10 - Add updated phpstan rule set

10 - Arranged according to property type

10 - Introduce reference page DTO, fix all failing test

10 - Resolve cs-fixer issues

10 - Resolve phpstan issues

10 - Resolve php cs fixer issues

10 - Created a reference directory for the Page DTO

10 - Remove manual loop for clean code readability

Co-authored-by: larry.sulebalogun <larry.sulebalogun@tillo.io>

src/Server/RequestHandler/ListPromptsHandler.php

@@ -12,6 +12,7 @@
 namespace Mcp\Server\RequestHandler;
 
 use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\ListPromptsRequest;
@@ -35,17 +36,18 @@ final class ListPromptsHandler implements MethodHandlerInterface
         return $message instanceof ListPromptsRequest;
     }
 
+    /**
+     * @throws InvalidCursorException
+     */
     public function handle(ListPromptsRequest|HasMethodInterface $message, SessionInterface $session): Response
     {
         \assert($message instanceof ListPromptsRequest);
 
-        $cursor = null;
-        $prompts = $this->registry->getPrompts($this->pageSize, $message->cursor);
-        $nextCursor = (null !== $cursor && \count($prompts) === $this->pageSize) ? $cursor : null;
+        $page = $this->registry->getPrompts($this->pageSize, $message->cursor);
 
         return new Response(
             $message->getId(),
-            new ListPromptsResult($prompts, $nextCursor),
+            new ListPromptsResult($page->references, $page->nextCursor),
         );
     }
 }

src/Server/RequestHandler/ListResourcesHandler.php

@@ -12,6 +12,7 @@
 namespace Mcp\Server\RequestHandler;
 
 use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\ListResourcesRequest;
@@ -35,17 +36,18 @@ final class ListResourcesHandler implements MethodHandlerInterface
         return $message instanceof ListResourcesRequest;
     }
 
+    /**
+     * @throws InvalidCursorException
+     */
     public function handle(ListResourcesRequest|HasMethodInterface $message, SessionInterface $session): Response
     {
         \assert($message instanceof ListResourcesRequest);
 
-        $cursor = null;
-        $resources = $this->registry->getResources($this->pageSize, $message->cursor);
-        $nextCursor = (null !== $cursor && \count($resources) === $this->pageSize) ? $cursor : null;
+        $page = $this->registry->getResources($this->pageSize, $message->cursor);
 
         return new Response(
             $message->getId(),
-            new ListResourcesResult($resources, $nextCursor),
+            new ListResourcesResult($page->references, $page->nextCursor),
         );
     }
 }

src/Server/RequestHandler/ListToolsHandler.php

@@ -12,6 +12,7 @@
 namespace Mcp\Server\RequestHandler;
 
 use Mcp\Capability\Registry\ReferenceProviderInterface;
+use Mcp\Exception\InvalidCursorException;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\ListToolsRequest;
@@ -36,17 +37,18 @@ final class ListToolsHandler implements MethodHandlerInterface
         return $message instanceof ListToolsRequest;
     }
 
+    /**
+     * @throws InvalidCursorException When the cursor is invalid
+     */
     public function handle(ListToolsRequest|HasMethodInterface $message, SessionInterface $session): Response
     {
         \assert($message instanceof ListToolsRequest);
 
-        $cursor = null;
-        $tools = $this->registry->getTools($this->pageSize, $message->cursor);
-        $nextCursor = (null !== $cursor && \count($tools) === $this->pageSize) ? $cursor : null;
+        $page = $this->registry->getTools($this->pageSize, $message->cursor);
 
         return new Response(
             $message->getId(),
-            new ListToolsResult($tools, $nextCursor),
+            new ListToolsResult($page->references, $page->nextCursor),
         );
     }
 }

src/Server/RequestHandler/Reference/Page.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Server\RequestHandler\Reference;
+
+/**
+ * @implements \ArrayAccess<int|string, mixed>
+ */
+final class Page implements \Countable, \ArrayAccess
+{
+    /**
+     * @param array<int|string, mixed> $references Items can be Tool, Prompt, ResourceTemplate, or Resource
+     */
+    public function __construct(
+        public readonly array $references,
+        public readonly ?string $nextCursor,
+    ) {
+    }
+
+    public function count(): int
+    {
+        return \count($this->references);
+    }
+
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->references[$offset]);
+    }
+
+    public function offsetGet(mixed $offset): mixed
+    {
+        return $this->references[$offset] ?? null;
+    }
+
+    public function offsetSet(mixed $offset, mixed $value): void
+    {
+        return;
+    }
+
+    public function offsetUnset(mixed $offset): void
+    {
+        return;
+    }
+}