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/Capability/Registry.php

@@ -22,11 +22,13 @@ use Mcp\Event\PromptListChangedEvent;
 use Mcp\Event\ResourceListChangedEvent;
 use Mcp\Event\ResourceTemplateListChangedEvent;
 use Mcp\Event\ToolListChangedEvent;
+use Mcp\Exception\InvalidCursorException;
 use Mcp\Schema\Prompt;
 use Mcp\Schema\Resource;
 use Mcp\Schema\ResourceTemplate;
 use Mcp\Schema\ServerCapabilities;
 use Mcp\Schema\Tool;
+use Mcp\Server\RequestHandler\Reference\Page;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
@@ -244,27 +246,92 @@ final class Registry implements ReferenceProviderInterface, ReferenceRegistryInt
         return $this->prompts[$name] ?? null;
     }
 
-    public function getTools(): array
+    public function getTools(?int $limit = null, ?string $cursor = null): Page
     {
-        return array_map(fn (ToolReference $tool) => $tool->tool, $this->tools);
-    }
+        $tools = [];
+        foreach ($this->tools as $toolReference) {
+            $tools[$toolReference->tool->name] = $toolReference->tool;
+        }
 
-    public function getResources(): array
-    {
-        return array_map(fn (ResourceReference $resource) => $resource->schema, $this->resources);
-    }
+        if (null === $limit) {
+            return new Page($tools, null);
+        }
 
-    public function getPrompts(): array
-    {
-        return array_map(fn (PromptReference $prompt) => $prompt->prompt, $this->prompts);
-    }
+        $paginatedTools = $this->paginateResults($tools, $limit, $cursor);
 
-    public function getResourceTemplates(): array
-    {
-        return array_map(
-            fn (ResourceTemplateReference $template) => $template->resourceTemplate,
-            $this->resourceTemplates
+        $nextCursor = $this->calculateNextCursor(
+            \count($tools),
+            $cursor,
+            $limit
         );
+
+        return new Page($paginatedTools, $nextCursor);
+    }
+
+    public function getResources(?int $limit = null, ?string $cursor = null): Page
+    {
+        $resources = [];
+        foreach ($this->resources as $resourceReference) {
+            $resources[$resourceReference->schema->uri] = $resourceReference->schema;
+        }
+
+        if (null === $limit) {
+            return new Page($resources, null);
+        }
+
+        $paginatedResources = $this->paginateResults($resources, $limit, $cursor);
+
+        $nextCursor = $this->calculateNextCursor(
+            \count($resources),
+            $cursor,
+            $limit
+        );
+
+        return new Page($paginatedResources, $nextCursor);
+    }
+
+    public function getPrompts(?int $limit = null, ?string $cursor = null): Page
+    {
+        $prompts = [];
+        foreach ($this->prompts as $promptReference) {
+            $prompts[$promptReference->prompt->name] = $promptReference->prompt;
+        }
+
+        if (null === $limit) {
+            return new Page($prompts, null);
+        }
+
+        $paginatedPrompts = $this->paginateResults($prompts, $limit, $cursor);
+
+        $nextCursor = $this->calculateNextCursor(
+            \count($prompts),
+            $cursor,
+            $limit
+        );
+
+        return new Page($paginatedPrompts, $nextCursor);
+    }
+
+    public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page
+    {
+        $templates = [];
+        foreach ($this->resourceTemplates as $templateReference) {
+            $templates[$templateReference->resourceTemplate->uriTemplate] = $templateReference->resourceTemplate;
+        }
+
+        if (null === $limit) {
+            return new Page($templates, null);
+        }
+
+        $paginatedTemplates = $this->paginateResults($templates, $limit, $cursor);
+
+        $nextCursor = $this->calculateNextCursor(
+            \count($templates),
+            $cursor,
+            $limit
+        );
+
+        return new Page($paginatedTemplates, $nextCursor);
     }
 
     public function hasElements(): bool
@@ -327,4 +394,63 @@ final class Registry implements ReferenceProviderInterface, ReferenceRegistryInt
             }
         }
     }
+
+    /**
+     * Calculate next cursor for pagination.
+     *
+     * @param int         $totalItems    Count of all items
+     * @param string|null $currentCursor Current cursor position
+     * @param int         $limit         Number requested/returned per page
+     */
+    private function calculateNextCursor(int $totalItems, ?string $currentCursor, int $limit): ?string
+    {
+        $currentOffset = 0;
+
+        if (null !== $currentCursor) {
+            $decodedCursor = base64_decode($currentCursor, true);
+            if (false !== $decodedCursor && is_numeric($decodedCursor)) {
+                $currentOffset = (int) $decodedCursor;
+            }
+        }
+
+        $nextOffset = $currentOffset + $limit;
+
+        if ($nextOffset < $totalItems) {
+            return base64_encode((string) $nextOffset);
+        }
+
+        return null;
+    }
+
+    /**
+     * Helper method to paginate results using cursor-based pagination.
+     *
+     * @param array<int|string, mixed> $items  The full array of items to paginate The full array of items to paginate
+     * @param int                      $limit  Maximum number of items to return
+     * @param string|null              $cursor Base64 encoded offset position
+     *
+     * @return array<int|string, mixed> Paginated results
+     *
+     * @throws InvalidCursorException When cursor is invalid (MCP error code -32602)
+     */
+    private function paginateResults(array $items, int $limit, ?string $cursor = null): array
+    {
+        $offset = 0;
+        if (null !== $cursor) {
+            $decodedCursor = base64_decode($cursor, true);
+
+            if (false === $decodedCursor || !is_numeric($decodedCursor)) {
+                throw new InvalidCursorException($cursor);
+            }
+
+            $offset = (int) $decodedCursor;
+
+            // Validate offset is within reasonable bounds
+            if ($offset < 0 || $offset > \count($items)) {
+                throw new InvalidCursorException($cursor);
+            }
+        }
+
+        return array_values(\array_slice($items, $offset, $limit));
+    }
 }

src/Capability/Registry/ReferenceProviderInterface.php

@@ -11,9 +11,7 @@
 
 namespace Mcp\Capability\Registry;
 
-use Mcp\Schema\Prompt;
-use Mcp\Schema\ResourceTemplate;
-use Mcp\Schema\Tool;
+use Mcp\Server\RequestHandler\Reference\Page;
 
 /**
  * Interface for providing access to registered MCP elements.
@@ -45,31 +43,23 @@ interface ReferenceProviderInterface
 
     /**
      * Gets all registered tools.
-     *
-     * @return array<string, Tool>
      */
-    public function getTools(): array;
+    public function getTools(?int $limit = null, ?string $cursor = null): Page;
 
     /**
      * Gets all registered resources.
-     *
-     * @return array<string, \Mcp\Schema\Resource>
      */
-    public function getResources(): array;
+    public function getResources(?int $limit = null, ?string $cursor = null): Page;
 
     /**
      * Gets all registered prompts.
-     *
-     * @return array<string, Prompt>
      */
-    public function getPrompts(): array;
+    public function getPrompts(?int $limit = null, ?string $cursor = null): Page;
 
     /**
      * Gets all registered resource templates.
-     *
-     * @return array<string, ResourceTemplate>
      */
-    public function getResourceTemplates(): array;
+    public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page;
 
     /**
      * Checks if any elements (manual or discovered) are currently registered.

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;
+    }
+}