[Server] Add Psr6SessionStore and Psr6NotificationBus (#635)

They work like their PSR-16 siblings over a PSR-6 cache pool. `Builder::setDiscovery()` also accepts a PSR-6 pool.

The sequence counter of `Psr16NotificationBus` no longer expires, so that its subscribers do not miss the notifications published after a quiet period.

Both notification buses read their backlog with one `getMultiple()` or `getItems()` call, not one call per entry.

Author: nicolas-grekas

CHANGELOG.md

@@ -10,6 +10,8 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * [BC Break] `DocBlockParser::parseDocBlock()` no longer accepts `null`; pass `ReflectionMethod::getDocComment()` as is
 * Fix tools with an array shape parameter whose keys are nullable or unions (e.g. `array{name: string, nickname: string|null}`) rejecting valid arguments with `-32602`: a `null` inside the shape no longer turns the parameter into `array|null`, and such keys get their own types instead of `object`, including lists and nested shapes (`string[]|null`, `array{x: int}|null`).
 * Fix `array<string|null>` and other generics with a union element getting `items` of type `object`. A `null` inside a generic no longer makes the parameter nullable, and neither does a DocBlock class whose name contains `null`.
+* Fix `Psr16NotificationBus` subscribers missing the notifications published after the bus stayed quiet for longer than its TTL: the sequence counter no longer expires, and a subscriber whose cursor is ahead of a lost counter reads what the bus holds.
+* Add `Psr6SessionStore` and `Psr6NotificationBus`, which work like `Psr16SessionStore` and `Psr16NotificationBus` over a PSR-6 cache pool. `Builder::setDiscovery()` also accepts a PSR-6 pool as `$cache`.
 
 ### Client
 

docs/get-started/installation.md

@@ -27,7 +27,7 @@ Which extras you need depends on what you build:
 | emit the response from a standalone HTTP entry point | `laminas/laminas-httphandlerrunner` |
 | [connect a client over HTTP](../client/transports.md) | any PSR-18 client, e.g. `symfony/http-client` |
 | [validate JWT access tokens](../run/authorization.md) | `firebase/php-jwt` |
-| store sessions, cache discovery or share notifications through a PSR-16 cache | `psr/simple-cache` implementation, e.g. `symfony/cache` |
+| store sessions, cache discovery or share notifications through a PSR-6 or PSR-16 cache | `psr/cache` or `psr/simple-cache` implementation, e.g. `symfony/cache` |
 | [fetch JWT keys from an issuer](../run/authorization.md) with `JwtTokenValidator::fromIssuer()` | `psr/cache` (PSR-6) implementation, e.g. `symfony/cache` |
 
 PSR-17 and PSR-18 implementations are found through

docs/run/server-builder.md

@@ -168,7 +168,7 @@ See [First server](../get-started/first-server.md) for the install command.
 - `$basePath` (string): Base directory for discovery (typically `__DIR__`)
 - `$scanDirs` (array): Directories to recursively scan for `#[McpTool]`, `#[McpResource]`, etc. All subdirectories are included. (default: `['.', 'src']`)
 - `$excludeDirs` (array): Directory names to exclude **within** the scanned directories during recursive scanning
-- `$cache` (CacheInterface|null): Optional PSR-16 cache to store discovered elements for performance
+- `$cache` (CacheInterface|CacheItemPoolInterface|null): Optional PSR-16 cache or PSR-6 pool to store discovered elements for performance
 - `$namePatterns` (array): Optional list of patterns (regexp, glob, or string) for file names (default: `['*.php']`)
 
 **Basic Discovery (scans current directory and `src/`):**
@@ -187,10 +187,9 @@ $server = Server::builder()
 ```php
 use Mcp\Server;
 use Symfony\Component\Cache\Adapter\FilesystemAdapter;
-use Symfony\Component\Cache\Psr16Cache;
 
 // Cache discovered elements to avoid filesystem scanning on every server start
-$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));
+$cache = new FilesystemAdapter('mcp-discovery');
 
 $server = Server::builder()
     ->setDiscovery(
@@ -274,15 +273,14 @@ use Mcp\Server;
 use Mcp\Server\Session\FileSessionStore;
 use Mcp\Capability\Registry\Container;
 use Symfony\Component\Cache\Adapter\FilesystemAdapter;
-use Symfony\Component\Cache\Psr16Cache;
 use Monolog\Logger;
 use Monolog\Handler\StreamHandler;
 
 // Setup dependencies
 $logger = new Logger('mcp-server');
 $logger->pushHandler(new StreamHandler('mcp.log', Logger::INFO));
 
-$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));
+$cache = new FilesystemAdapter('mcp-discovery');
 $sessionStore = new FileSessionStore(__DIR__ . '/sessions');
 
 // Setup container with dependencies

docs/run/sessions.md

@@ -12,6 +12,7 @@ use Mcp\Server;
 use Mcp\Server\Session\FileSessionStore;
 use Mcp\Server\Session\InMemorySessionStore;
 use Mcp\Server\Session\Psr16SessionStore;
+use Mcp\Server\Session\Psr6SessionStore;
 use Symfony\Component\Cache\Psr16Cache;
 use Symfony\Component\Cache\Adapter\RedisAdapter;
 
@@ -25,34 +26,40 @@ $server = Server::builder()
     ->setSession(new InMemorySessionStore(3600))
     ->build();
 
-// Override with PSR-16 cache-based storage
-// Requires psr/simple-cache and symfony/cache (or any other PSR-16 implementation)
-// composer require psr/simple-cache symfony/cache
+// Override with PSR-6 cache-based storage
+// Requires symfony/cache (or any other PSR-6 implementation)
+// composer require symfony/cache
 $redisAdapter = new RedisAdapter(
     RedisAdapter::createConnection('redis://localhost:6379'),
     'mcp_sessions'
 );
 
 $server = Server::builder()
-    ->setSession(new Psr16SessionStore(
-        cache: new Psr16Cache($redisAdapter),
+    ->setSession(new Psr6SessionStore(
+        cache: $redisAdapter,
         prefix: 'mcp-',
         ttl: 3600
     ))
     ->build();
+
+// Override with PSR-16 cache-based storage, which takes the same arguments
+// Requires psr/simple-cache and a PSR-16 implementation
+$server = Server::builder()
+    ->setSession(new Psr16SessionStore(new Psr16Cache($redisAdapter)))
+    ->build();
 ```
 
 ## Sessions over HTTP
 
 With HTTP, PHP often serves each request in a different process (e.g. PHP-FPM workers).
 `InMemorySessionStore` keeps sessions in the memory of one process, so the next request
 doesn't find them. Use a store that all processes share, like `FileSessionStore` on a shared
-directory or `Psr16SessionStore` with a shared cache such as Redis.
+directory or `Psr6SessionStore` (or `Psr16SessionStore`) with a shared cache such as Redis.
 
 `FileSessionStore` suits a single host. Once requests are spread over several hosts, or sessions number in the
-tens of thousands, use `Psr16SessionStore` with Redis or a similar shared cache: it is shared across hosts,
-expires sessions on its own and needs no garbage collection (see below). A network-mounted directory adds latency and
-makes session availability depend on the shared filesystem.
+tens of thousands, use `Psr6SessionStore` or `Psr16SessionStore` with Redis or a similar shared cache: it is shared
+across hosts, expires sessions on its own and needs no garbage collection (see below). A network-mounted directory adds
+latency and makes session availability depend on the shared filesystem.
 
 ## Garbage Collection Configuration
 
@@ -113,7 +120,8 @@ $server = Server::builder()
     ->build();
 ```
 
-`Psr16SessionStore` doesn't scan anything: it stores each session with the TTL, and its `gc()` does nothing.
+`Psr6SessionStore` and `Psr16SessionStore` don't scan anything. They store each session with the TTL, and their `gc()`
+does nothing.
 With a cache like Redis, the cache expires the keys itself.
 
 **Parameters:**
@@ -153,17 +161,16 @@ For a store shared across machines, use `SymfonyLockSessionLock` with any
 [symfony/lock](https://symfony.com/doc/current/components/lock.html) store (`composer require symfony/lock`):
 
 ```php
-use Mcp\Server\Session\Psr16SessionStore;
+use Mcp\Server\Session\Psr6SessionStore;
 use Mcp\Server\Session\SymfonyLockSessionLock;
 use Symfony\Component\Cache\Adapter\RedisAdapter;
-use Symfony\Component\Cache\Psr16Cache;
 use Symfony\Component\Lock\LockFactory;
 use Symfony\Component\Lock\Store\RedisStore;
 
 $redis = RedisAdapter::createConnection('redis://localhost:6379');
 
 $server = Server::builder()
-    ->setSession(new Psr16SessionStore(new Psr16Cache(new RedisAdapter($redis, 'mcp_sessions'))))
+    ->setSession(new Psr6SessionStore(new RedisAdapter($redis, 'mcp_sessions')))
     ->setSessionLock(new SymfonyLockSessionLock(new LockFactory(new RedisStore($redis))))
     ->build();
 ```
@@ -200,6 +207,7 @@ right now and returns `false` otherwise; `release()` gives it back.
 
 - `InMemorySessionStore`: Fast in-memory storage (default)
 - `FileSessionStore`: Persistent file-based storage
+- `Psr6SessionStore`: PSR-6 compliant cache-based storage
 - `Psr16SessionStore`: PSR-16 compliant cache-based storage
 
 **Custom Session Stores:**

docs/run/subscriptions.md

@@ -19,12 +19,14 @@ open are often not the same one:
 ```php
 use Mcp\Server\Subscription\InMemoryNotificationBus;
 use Mcp\Server\Subscription\Psr16NotificationBus;
+use Mcp\Server\Subscription\Psr6NotificationBus;
 
 // stdio, or a persistent runtime where the whole server is one process
 ->setNotificationBus(new InMemoryNotificationBus())
 
 // PHP-FPM: the publisher and the stream are different workers
-->setNotificationBus(new Psr16NotificationBus($cache))
+->setNotificationBus(new Psr6NotificationBus($cachePool))   // a PSR-6 pool
+->setNotificationBus(new Psr16NotificationBus($cache))      // or a PSR-16 cache
 ```
 
 Registry changes (`registerTool()`, `unregisterPrompt()`, …) are published automatically, with or

examples/server/stateless-lifecycle/server.php

@@ -92,8 +92,8 @@
 
     // Carries change notifications to open `subscriptions/listen` streams.
     // In-memory suits `php -S` and worker runtimes; under PHP-FPM use
-    // Psr16NotificationBus, since the publisher and the stream are different
-    // processes there.
+    // Psr6NotificationBus or Psr16NotificationBus, since the publisher and the
+    // stream are different processes there.
     ->setNotificationBus($bus)
     ->setSubscriptionLifetime(20.0)
 

src/Capability/Discovery/CachedDiscoverer.php

@@ -11,6 +11,7 @@
 
 namespace Mcp\Capability\Discovery;
 
+use Psr\Cache\CacheItemPoolInterface;
 use Psr\Log\LoggerInterface;
 use Psr\SimpleCache\CacheInterface;
 
@@ -30,7 +31,7 @@ final class CachedDiscoverer implements DiscovererInterface
 
     public function __construct(
         private readonly DiscovererInterface $discoverer,
-        private readonly CacheInterface $cache,
+        private readonly CacheInterface|CacheItemPoolInterface $cache,
         private readonly LoggerInterface $logger,
     ) {
     }
@@ -47,7 +48,13 @@ public function discover(string $basePath, array $directories, array $excludeDir
     {
         $cacheKey = $this->generateCacheKey($basePath, $directories, $excludeDirs);
 
-        $cachedResult = $this->cache->get($cacheKey);
+        if ($this->cache instanceof CacheItemPoolInterface) {
+            $item = $this->cache->getItem($cacheKey);
+            $cachedResult = $item->get();
+        } else {
+            $cachedResult = $this->cache->get($cacheKey);
+        }
+
         if (null !== $cachedResult) {
             $this->logger->debug('Using cached discovery results', [
                 'cache_key' => $cacheKey,
@@ -66,7 +73,11 @@ public function discover(string $basePath, array $directories, array $excludeDir
 
         $discoveryState = $this->discoverer->discover($basePath, $directories, $excludeDirs, $namePatterns);
 
-        $this->cache->set($cacheKey, $discoveryState);
+        if ($this->cache instanceof CacheItemPoolInterface) {
+            $this->cache->save($item->set($discoveryState));
+        } else {
+            $this->cache->set($cacheKey, $discoveryState);
+        }
 
         return $discoveryState;
     }

src/Server/Builder.php

@@ -64,8 +64,10 @@
 use Mcp\Server\Subscription\InMemoryNotificationBus;
 use Mcp\Server\Subscription\NotificationBusInterface;
 use Mcp\Server\Subscription\Psr16NotificationBus;
+use Mcp\Server\Subscription\Psr6NotificationBus;
 use Mcp\Server\Subscription\PublishingEventDispatcher;
 use Mcp\Server\Wire\CachePolicy;
+use Psr\Cache\CacheItemPoolInterface;
 use Psr\Container\ContainerInterface;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
@@ -99,7 +101,7 @@ final class Builder
 
     private ?LoggerInterface $logger = null;
 
-    private ?CacheInterface $discoveryCache = null;
+    private CacheInterface|CacheItemPoolInterface|null $discoveryCache = null;
 
     private ?EventDispatcherInterface $eventDispatcher = null;
 
@@ -311,7 +313,8 @@ public function setServerInfo(
      * the publisher and the stream share a process.
      * {@see InMemoryNotificationBus} is correct for stdio and persistent
      * runtimes; under PHP-FPM, where they are different workers, use
-     * {@see Psr16NotificationBus} or an implementation over your own broker.
+     * {@see Psr6NotificationBus}, {@see Psr16NotificationBus} or an
+     * implementation over your own broker.
      *
      * With the built-in registry, registry changes are published automatically,
      * with or without an event dispatcher, and `listChanged` is announced. A
@@ -669,7 +672,7 @@ public function setDiscovery(
         string $basePath,
         array $scanDirs = ['.', 'src'],
         array $excludeDirs = [],
-        ?CacheInterface $cache = null,
+        CacheInterface|CacheItemPoolInterface|null $cache = null,
         array $namePatterns = DiscovererInterface::DEFAULT_NAME_PATERNS,
     ): self {
         $this->discoveryBasePath = $basePath;

src/Server/Session/Psr6SessionStore.php

@@ -0,0 +1,65 @@
+<?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\Session;
+
+use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * Session store over any PSR-6 cache pool.
+ *
+ * Each session is stored under the prefix followed by the session id, the same
+ * key as {@see Psr16SessionStore}.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+final class Psr6SessionStore implements SessionStoreInterface
+{
+    public function __construct(
+        private readonly CacheItemPoolInterface $cache,
+        private readonly string $prefix = 'mcp-',
+        private readonly int $ttl = 3600,
+    ) {
+    }
+
+    public function exists(Uuid $id): bool
+    {
+        return $this->cache->hasItem($this->getKey($id));
+    }
+
+    public function read(Uuid $id): string|false
+    {
+        return $this->cache->getItem($this->getKey($id))->get() ?? false;
+    }
+
+    public function write(Uuid $id, string $data): bool
+    {
+        $item = $this->cache->getItem($this->getKey($id));
+
+        return $this->cache->save($item->set($data)->expiresAfter($this->ttl));
+    }
+
+    public function destroy(Uuid $id): bool
+    {
+        return $this->cache->deleteItem($this->getKey($id));
+    }
+
+    public function gc(): array
+    {
+        return [];
+    }
+
+    private function getKey(Uuid $id): string
+    {
+        return $this->prefix.$id;
+    }
+}

src/Server/Subscription/InMemoryNotificationBus.php

@@ -21,7 +21,8 @@
  * one process (Swoole, FrankenPHP worker mode, ReactPHP). Under PHP-FPM it is
  * not: the worker that publishes and the worker holding the stream open are
  * different processes, and a notification published in one is invisible to the
- * other. {@see Psr16NotificationBus} is the answer there.
+ * other. {@see Psr6NotificationBus} or {@see Psr16NotificationBus} is the
+ * answer there.
  *
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */