[Server] Implement discovery caching for improved performance (#39)

* feat: implement discovery caching with state-based approach

- Add DiscoveryState class to encapsulate discovered MCP capabilities
- Add exportDiscoveryState and importDiscoveryState methods to Registry
- Modify Discoverer to return DiscoveryState instead of void
- Create CachedDiscoverer decorator for caching discovery results
- Add importDiscoveryState method to ReferenceRegistryInterface
- Update ServerBuilder to use caching with withCache() method
- Update tests to work with new state-based approach
- Add example demonstrating cached discovery functionality
- Add PSR-16 SimpleCache and Symfony Cache dependencies

* docs: add comprehensive discovery caching documentation

- Add detailed documentation explaining discovery caching architecture
- Include usage examples for different cache implementations
- Document performance benefits and best practices
- Add troubleshooting guide and migration instructions
- Include complete API reference for all caching components
- Fix PHPStan issues by regenerating baseline
- Apply PHP CS Fixer formatting to all new files

* refactor: address reviewer feedback and clean up discovery caching

- Make DiscoveryState class final
- Cache DiscoveryState objects directly instead of arrays (no serialization needed)
- Rename exportDiscoveryState/importDiscoveryState to getDiscoveryState/setDiscoveryState
- Add getDiscoveryState method to ReferenceRegistryInterface
- Remove TTL parameter from CachedDiscoverer (no expiration by default)
- Remove unused methods from DiscoveryState (toArray, fromArray, merge)
- Simplify ServerBuilder to handle decoration internally
- Make Discoverer.applyDiscoveryState() internal (no longer public API)
- Simplify documentation to focus on user perspective
- Remove unnecessary development comments
- Update all tests to work with new architecture
- All tests pass, PHPStan clean, code formatting applied

* refactor: clean up comments and formatting in server.php example

* refactor: improve code formatting and consistency in discovery classes and example server

* Fix method names in cached discovery example

- Change withServerInfo() to setServerInfo()
- Change withDiscovery() to setDiscovery()
- Change withLogger() to setLogger()
- Fixes PHPStan static analysis errors

* refactor: update method names in ServerBuilder for consistency

- Change withCache() to setCache() in ServerBuilder
- Update example and documentation to reflect method name changes
- Ensure consistency across caching implementation in examples and documentation

* refactor: reorganize examples and fix PHPStan baseline

- Move cached discovery example from examples/10 to examples/09
- Update composer.json autoload-dev namespace mapping
- Fix PHPStan baseline by removing invalid entries for non-existent files
- Update server.php to follow proper example pattern with logging and lifecycle

* fix: correct formatting in server.php

examples/09-cached-discovery-stdio/CachedCalculatorElements.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Example\CachedDiscoveryExample;
+
+use Mcp\Capability\Attribute\McpTool;
+
+/**
+ * Example MCP elements for demonstrating cached discovery.
+ *
+ * This class contains simple calculator tools that will be discovered
+ * and cached for improved performance on subsequent server starts.
+ */
+class CachedCalculatorElements
+{
+    #[McpTool(name: 'add_numbers')]
+    public function add(int $a, int $b): int
+    {
+        return $a + $b;
+    }
+
+    #[McpTool(name: 'multiply_numbers')]
+    public function multiply(int $a, int $b): int
+    {
+        return $a * $b;
+    }
+
+    #[McpTool(name: 'divide_numbers')]
+    public function divide(int $a, int $b): float
+    {
+        if (0 === $b) {
+            throw new \InvalidArgumentException('Division by zero is not allowed');
+        }
+
+        return $a / $b;
+    }
+
+    #[McpTool(name: 'power')]
+    public function power(int $base, int $exponent): int
+    {
+        return (int) $base ** $exponent;
+    }
+}

examples/09-cached-discovery-stdio/server.php

@@ -0,0 +1,39 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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.
+ */
+
+require_once dirname(__DIR__).'/bootstrap.php';
+chdir(__DIR__);
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+use Symfony\Component\Cache\Psr16Cache;
+
+logger()->info('Starting MCP Cached Discovery Calculator Server...');
+
+$server = Server::make()
+    ->setServerInfo('Cached Discovery Calculator', '1.0.0', 'Calculator with cached discovery for better performance.')
+    ->setContainer(container())
+    ->setLogger(logger())
+    ->setDiscovery(__DIR__, ['.'])
+    ->setCache(new Psr16Cache(new ArrayAdapter()))
+    ->build();
+
+$transport = new StdioTransport(logger: logger());
+
+$server->connect($transport);
+
+$transport->listen();
+
+logger()->info('Server listener stopped gracefully.');