Add support for pagination

Nyholm · Nyholm · commit 1fc5e9c33249 · 2025-05-29T21:45:17.000+02:00
diff --git a/src/mcp-sdk/src/Capability/Prompt/CollectionInterface.php b/src/mcp-sdk/src/Capability/Prompt/CollectionInterface.php
@@ -13,10 +13,16 @@
 
 namespace Symfony\AI\McpSdk\Capability\Prompt;
 
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
+
 interface CollectionInterface
 {
     /**
-     * @return MetadataInterface[]
+     * @param int $count the number of metadata items to return
+     *
+     * @return iterable<MetadataInterface>
+     *
+     * @throws InvalidCursorException if no item with $lastIdentifier was found
      */
-    public function getMetadata(): array;
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable;
 }
diff --git a/src/mcp-sdk/src/Capability/PromptChain.php b/src/mcp-sdk/src/Capability/PromptChain.php
@@ -19,6 +19,7 @@
 use Symfony\AI\McpSdk\Capability\Prompt\PromptGet;
 use Symfony\AI\McpSdk\Capability\Prompt\PromptGetResult;
 use Symfony\AI\McpSdk\Capability\Prompt\PromptGetterInterface;
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
 use Symfony\AI\McpSdk\Exception\PromptGetException;
 use Symfony\AI\McpSdk\Exception\PromptNotFoundException;
 
@@ -35,9 +36,28 @@ public function __construct(
     ) {
     }
 
-    public function getMetadata(): array
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable
     {
-        return array_filter($this->items, fn ($item) => $item instanceof MetadataInterface);
+        $found = null === $lastIdentifier;
+        foreach ($this->items as $item) {
+            if (!$item instanceof MetadataInterface) {
+                continue;
+            }
+
+            if (false === $found) {
+                $found = $item->getName() === $lastIdentifier;
+                continue;
+            }
+
+            yield $item;
+            if (--$count <= 0) {
+                break;
+            }
+        }
+
+        if (!$found) {
+            throw new InvalidCursorException($lastIdentifier);
+        }
     }
 
     public function get(PromptGet $input): PromptGetResult
diff --git a/src/mcp-sdk/src/Capability/Resource/CollectionInterface.php b/src/mcp-sdk/src/Capability/Resource/CollectionInterface.php
@@ -13,10 +13,16 @@
 
 namespace Symfony\AI\McpSdk\Capability\Resource;
 
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
+
 interface CollectionInterface
 {
     /**
-     * @return MetadataInterface[]
+     * @param int $count the number of metadata items to return
+     *
+     * @return iterable<MetadataInterface>
+     *
+     * @throws InvalidCursorException if no item with $lastIdentifier was found
      */
-    public function getMetadata(): array;
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable;
 }
diff --git a/src/mcp-sdk/src/Capability/ResourceChain.php b/src/mcp-sdk/src/Capability/ResourceChain.php
@@ -19,6 +19,7 @@
 use Symfony\AI\McpSdk\Capability\Resource\ResourceRead;
 use Symfony\AI\McpSdk\Capability\Resource\ResourceReaderInterface;
 use Symfony\AI\McpSdk\Capability\Resource\ResourceReadResult;
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
 use Symfony\AI\McpSdk\Exception\ResourceNotFoundException;
 use Symfony\AI\McpSdk\Exception\ResourceReadException;
 
@@ -35,9 +36,28 @@ public function __construct(
     ) {
     }
 
-    public function getMetadata(): array
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable
     {
-        return array_filter($this->items, fn ($item) => $item instanceof MetadataInterface);
+        $found = null === $lastIdentifier;
+        foreach ($this->items as $item) {
+            if (!$item instanceof MetadataInterface) {
+                continue;
+            }
+
+            if (false === $found) {
+                $found = $item->getUri() === $lastIdentifier;
+                continue;
+            }
+
+            yield $item;
+            if (--$count <= 0) {
+                break;
+            }
+        }
+
+        if (!$found) {
+            throw new InvalidCursorException($lastIdentifier);
+        }
     }
 
     public function read(ResourceRead $input): ResourceReadResult
diff --git a/src/mcp-sdk/src/Capability/Tool/CollectionInterface.php b/src/mcp-sdk/src/Capability/Tool/CollectionInterface.php
@@ -13,10 +13,16 @@
 
 namespace Symfony\AI\McpSdk\Capability\Tool;
 
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
+
 interface CollectionInterface
 {
     /**
-     * @return MetadataInterface[]
+     * @param int $count the number of metadata items to return
+     *
+     * @return iterable<MetadataInterface>
+     *
+     * @throws InvalidCursorException if no item with $lastIdentifier was found
      */
-    public function getMetadata(): array;
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable;
 }
diff --git a/src/mcp-sdk/src/Capability/ToolChain.php b/src/mcp-sdk/src/Capability/ToolChain.php
@@ -19,6 +19,7 @@
 use Symfony\AI\McpSdk\Capability\Tool\ToolCall;
 use Symfony\AI\McpSdk\Capability\Tool\ToolCallResult;
 use Symfony\AI\McpSdk\Capability\Tool\ToolExecutorInterface;
+use Symfony\AI\McpSdk\Exception\InvalidCursorException;
 use Symfony\AI\McpSdk\Exception\ToolExecutionException;
 use Symfony\AI\McpSdk\Exception\ToolNotFoundException;
 
@@ -35,9 +36,28 @@ public function __construct(
     ) {
     }
 
-    public function getMetadata(): array
+    public function getMetadata(int $count, ?string $lastIdentifier = null): iterable
     {
-        return array_filter($this->items, fn ($item) => $item instanceof MetadataInterface);
+        $found = null === $lastIdentifier;
+        foreach ($this->items as $item) {
+            if (!$item instanceof MetadataInterface) {
+                continue;
+            }
+
+            if (false === $found) {
+                $found = $item->getName() === $lastIdentifier;
+                continue;
+            }
+
+            yield $item;
+            if (--$count <= 0) {
+                break;
+            }
+        }
+
+        if (!$found) {
+            throw new InvalidCursorException($lastIdentifier);
+        }
     }
 
     public function call(ToolCall $input): ToolCallResult
diff --git a/src/mcp-sdk/src/Exception/ExceptionInterface.php b/src/mcp-sdk/src/Exception/ExceptionInterface.php
@@ -13,6 +13,6 @@
 
 namespace Symfony\AI\McpSdk\Exception;
 
-interface ExceptionInterface
+interface ExceptionInterface extends \Throwable
 {
 }
diff --git a/src/mcp-sdk/src/Exception/HandlerNotFoundException.php b/src/mcp-sdk/src/Exception/HandlerNotFoundException.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\McpSdk\Exception;
+
+class HandlerNotFoundException extends \InvalidArgumentException implements NotFoundExceptionInterface
+{
+}
diff --git a/src/mcp-sdk/src/Exception/InvalidCursorException.php b/src/mcp-sdk/src/Exception/InvalidCursorException.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\McpSdk\Exception;
+
+final class InvalidCursorException extends \InvalidArgumentException implements ExceptionInterface
+{
+    public function __construct(
+        public readonly string $cursor,
+    ) {
+        parent::__construct(\sprintf('Invalid value for pagination parameter "cursor": "%s"', $cursor));
+    }
+}
diff --git a/src/mcp-sdk/src/Exception/PromptNotFoundException.php b/src/mcp-sdk/src/Exception/PromptNotFoundException.php
@@ -20,6 +20,6 @@ final class PromptNotFoundException extends \RuntimeException implements NotFoun
     public function __construct(
         public readonly PromptGet $promptGet,
     ) {
-        parent::__construct(\sprintf('Resource not found for uri: "%s"', $promptGet->name));
+        parent::__construct(\sprintf('Prompt not found for name: "%s"', $promptGet->name));
     }
 }
diff --git a/src/mcp-sdk/src/Server/JsonRpcHandler.php b/src/mcp-sdk/src/Server/JsonRpcHandler.php
@@ -14,11 +14,14 @@
 namespace Symfony\AI\McpSdk\Server;
 
 use Psr\Log\LoggerInterface;
+use Symfony\AI\McpSdk\Exception\HandlerNotFoundException;
+use Symfony\AI\McpSdk\Exception\NotFoundExceptionInterface;
 use Symfony\AI\McpSdk\Message\Error;
 use Symfony\AI\McpSdk\Message\Factory;
 use Symfony\AI\McpSdk\Message\Notification;
 use Symfony\AI\McpSdk\Message\Request;
 use Symfony\AI\McpSdk\Message\Response;
+use Symfony\Component\String\Exception\ExceptionInterface;
 
 /**
  * @final
@@ -76,10 +79,14 @@ public function process(string $message): ?string
                 : $this->encodeResponse($this->handleRequest($message));
         } catch (\DomainException) {
             return null;
-        } catch (\InvalidArgumentException $e) {
+        } catch (NotFoundExceptionInterface $e) {
             $this->logger->warning(\sprintf('Failed to create response: %s', $e->getMessage()), ['exception' => $e]);
 
             return $this->encodeResponse(Error::methodNotFound($message->id ?? 0, $e->getMessage()));
+        } catch (\InvalidArgumentException $e) {
+            $this->logger->warning(\sprintf('Invalid argument: %s', $e->getMessage()), ['exception' => $e]);
+
+            return $this->encodeResponse(Error::invalidParams($message->id ?? 0, $e->getMessage()));
         }
     }
 
@@ -113,6 +120,10 @@ private function handleNotification(Notification $notification): null
         return null;
     }
 
+    /**
+     * @throws NotFoundExceptionInterface
+     * @throws ExceptionInterface
+     */
     private function handleRequest(Request $request): Response|Error
     {
         foreach ($this->requestHandlers as $handler) {
@@ -121,6 +132,6 @@ private function handleRequest(Request $request): Response|Error
             }
         }
 
-        throw new \InvalidArgumentException(\sprintf('No handler found for method "%s".', $request->method));
+        throw new HandlerNotFoundException(\sprintf('No handler found for method "%s".', $request->method));
     }
 }
diff --git a/src/mcp-sdk/src/Server/RequestHandler/PromptListHandler.php b/src/mcp-sdk/src/Server/RequestHandler/PromptListHandler.php
@@ -15,50 +15,60 @@
 
 use Symfony\AI\McpSdk\Capability\Prompt\CollectionInterface;
 use Symfony\AI\McpSdk\Capability\Prompt\MetadataInterface;
-use Symfony\AI\McpSdk\Message\Notification;
 use Symfony\AI\McpSdk\Message\Request;
 use Symfony\AI\McpSdk\Message\Response;
 
 final class PromptListHandler extends BaseRequestHandler
 {
     public function __construct(
         private readonly CollectionInterface $collection,
+        private readonly int $pageSize = 20,
     ) {
     }
 
-    public function createResponse(Request|Notification $message): Response
+    public function createResponse(Request $message): Response
     {
-        return new Response($message->id, [
-            'prompts' => array_map(function (MetadataInterface $metadata) {
-                $result = [
-                    'name' => $metadata->getName(),
+        $nextCursor = null;
+        $prompts = array_map(function (MetadataInterface $metadata) use (&$nextCursor) {
+            $nextCursor = $metadata->getName();
+            $result = [
+                'name' => $metadata->getName(),
+            ];
+
+            $description = $metadata->getDescription();
+            if (null !== $description) {
+                $result['description'] = $description;
+            }
+
+            $arguments = [];
+            foreach ($metadata->getArguments() as $data) {
+                $argument = [
+                    'name' => $data['name'],
+                    'required' => $data['required'] ?? false,
                 ];
 
-                $description = $metadata->getDescription();
-                if (null !== $description) {
-                    $result['description'] = $description;
+                if (isset($data['description'])) {
+                    $argument['description'] = $data['description'];
                 }
+                $arguments[] = $argument;
+            }
 
-                $arguments = [];
-                foreach ($metadata->getArguments() as $data) {
-                    $argument = [
-                        'name' => $data['name'],
-                        'required' => $data['required'] ?? false,
-                    ];
+            if ([] !== $arguments) {
+                $result['arguments'] = $arguments;
+            }
 
-                    if (isset($data['description'])) {
-                        $argument['description'] = $data['description'];
-                    }
-                    $arguments[] = $argument;
-                }
+            return $result;
+        }, $this->collection->getMetadata($this->pageSize, $message->params['cursor'] ?? null));
 
-                if ([] !== $arguments) {
-                    $result['arguments'] = $arguments;
-                }
+        $result = [
+            'prompts' => $prompts,
+        ];
+
+        if (null !== $nextCursor && \count($prompts) === $this->pageSize) {
+            $result['nextCursor'] = $nextCursor;
+        }
 
-                return $result;
-            }, $this->collection->getMetadata()),
-        ]);
+        return new Response($message->id, $result);
     }
 
     protected function supportedMethod(): string
diff --git a/src/mcp-sdk/src/Server/RequestHandler/ResourceListHandler.php b/src/mcp-sdk/src/Server/RequestHandler/ResourceListHandler.php
diff --git a/src/mcp-sdk/src/Server/RequestHandler/ToolListHandler.php b/src/mcp-sdk/src/Server/RequestHandler/ToolListHandler.php

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,6 @@`
`13`	`13`
`14`	`14`	`namespace Symfony\AI\McpSdk\Exception;`
`15`	`15`
`16`		`-interface ExceptionInterface`
	`16`	`+interface ExceptionInterface extends \Throwable`
`17`	`17`	`{`
`18`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,6 @@ final class PromptNotFoundException extends \RuntimeException implements NotFoun`
`20`	`20`	`public function __construct(`
`21`	`21`	`public readonly PromptGet $promptGet,`
`22`	`22`	`) {`
`23`		`- parent::__construct(\sprintf('Resource not found for uri: "%s"', $promptGet->name));`
	`23`	`+ parent::__construct(\sprintf('Prompt not found for name: "%s"', $promptGet->name));`
`24`	`24`	`}`
`25`	`25`	`}`