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

Author: xentixar

docs/discovery-caching.md

@@ -1,33 +1,15 @@
 # Discovery Caching
 
-This document explains the discovery caching feature in the PHP MCP SDK, which improves performance by caching the results of file system operations and reflection during MCP element discovery.
+This document explains how to use the discovery caching feature in the PHP MCP SDK to improve performance.
 
 ## Overview
 
-The discovery caching system allows you to cache the results of MCP element discovery to avoid repeated file system scanning and reflection operations. This is particularly useful in:
+The discovery caching system caches the results of MCP element discovery to avoid repeated file system scanning and reflection operations. This is particularly useful in:
 
 - **Development environments** where the server is restarted frequently
 - **Production environments** where discovery happens on every request
 - **Large codebases** with many MCP elements to discover
 
-## Architecture
-
-The caching system is built around a state-based approach that eliminates the need for reflection to access private registry state:
-
-### Core Components
-
-1. **`DiscoveryState`** - A value object that encapsulates all discovered MCP capabilities
-2. **`CachedDiscoverer`** - A decorator that wraps the `Discoverer` and provides caching functionality
-3. **`Registry`** - Enhanced with `exportDiscoveryState()` and `importDiscoveryState()` methods
-4. **`ServerBuilder`** - Updated with `withCache()` method for easy cache configuration
-
-### Key Benefits
-
-- **No Reflection Required**: Uses clean public APIs instead of accessing private state
-- **State-Based**: Encapsulates discovered elements in a dedicated state object
-- **PSR-16 Compatible**: Works with any PSR-16 SimpleCache implementation
-- **Backward Compatible**: Existing code continues to work without changes
-
 ## Usage
 
 ### Basic Setup
@@ -49,112 +31,30 @@ $server = Server::make()
 The caching system works with any PSR-16 SimpleCache implementation. Popular options include:
 
 #### Symfony Cache
+
 ```php
 use Symfony\Component\Cache\Adapter\ArrayAdapter;
 use Symfony\Component\Cache\Adapter\FilesystemAdapter;
-use Symfony\Component\Cache\Adapter\RedisAdapter;
 use Symfony\Component\Cache\Psr16Cache;
 
 // In-memory cache (development)
 $cache = new Psr16Cache(new ArrayAdapter());
 
 // Filesystem cache (production)
-$cache = new Psr16Cache(new FilesystemAdapter('cache', 0, __DIR__ . '/var/cache'));
-
-// Redis cache (distributed)
-$cache = new Psr16Cache(new RedisAdapter($redisClient));
+$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery', 0, '/var/cache'));
 ```
 
 #### Other PSR-16 Implementations
+
 ```php
 use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\Cache\ArrayCache;
 
-// Doctrine cache
-$doctrineCache = new ArrayCache();
-$cache = DoctrineProvider::wrap($doctrineCache);
-```
-
-## Configuration
-
-### Cache TTL (Time To Live)
-
-The default cache TTL is 1 hour (3600 seconds). You can customize this when creating the `CachedDiscoverer`:
-
-```php
-use Mcp\Capability\Discovery\CachedDiscoverer;
-use Mcp\Capability\Discovery\Discoverer;
-
-$discoverer = new Discoverer($registry, $logger);
-$cachedDiscoverer = new CachedDiscoverer(
-    $discoverer,
-    $cache,
-    $logger,
-    7200 // 2 hours TTL
-);
-```
-
-### Cache Key Generation
-
-Cache keys are automatically generated based on:
-- Base path for discovery
-- Directories to scan
-- Exclude directories
-- File modification times (implicitly through file system state)
-
-This ensures that cache invalidation happens automatically when files change.
-
-## Advanced Usage
-
-### Manual Cache Management
-
-```php
-use Mcp\Capability\Discovery\CachedDiscoverer;
-
-$cachedDiscoverer = new CachedDiscoverer($discoverer, $cache, $logger);
-
-// Clear the entire discovery cache
-$cachedDiscoverer->clearCache();
-
-// Discovery with caching
-$discoveryState = $cachedDiscoverer->discover('/path', ['.'], []);
-```
-
-### Custom Discovery State Handling
-
-```php
-use Mcp\Capability\Discovery\DiscoveryState;
-use Mcp\Capability\Discovery\Discoverer;
-
-$discoverer = new Discoverer($registry, $logger);
-
-// Discover elements
-$discoveryState = $discoverer->discover('/path', ['.'], []);
-
-// Check what was discovered
-echo "Discovered " . $discoveryState->getElementCount() . " elements\n";
-$counts = $discoveryState->getElementCounts();
-echo "Tools: {$counts['tools']}, Resources: {$counts['resources']}\n";
-
-// Apply to registry
-$discoverer->applyDiscoveryState($discoveryState);
+$cache = DoctrineProvider::wrap(new ArrayCache());
 ```
 
 ## Performance Benefits
 
-### Before Caching
-- File system scanning on every discovery
-- Reflection operations for each MCP element
-- Schema generation for each tool/resource
-- DocBlock parsing for each method
-
-### After Caching
-- File system scanning only on cache miss
-- Cached reflection results
-- Pre-generated schemas
-- Cached docBlock parsing results
-
-### Typical Performance Improvements
 - **First run**: Same as without caching
 - **Subsequent runs**: 80-95% faster discovery
 - **Memory usage**: Slightly higher due to cache storage
@@ -163,6 +63,7 @@ $discoverer->applyDiscoveryState($discoveryState);
 ## Best Practices
 
 ### Development Environment
+
 ```php
 // Use in-memory cache for fast development cycles
 $cache = new Psr16Cache(new ArrayAdapter());
@@ -174,153 +75,35 @@ $server = Server::make()
 ```
 
 ### Production Environment
+
 ```php
-// Use persistent cache with appropriate TTL
-$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery', 3600, '/var/cache'));
+// Use persistent cache
+$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery', 0, '/var/cache'));
 
 $server = Server::make()
     ->withDiscovery(__DIR__, ['.'])
     ->withCache($cache)
     ->build();
 ```
 
-### Cache Invalidation
+## Cache Invalidation
+
 The cache automatically invalidates when:
+
 - Discovery parameters change (base path, directories, exclude patterns)
 - Files are modified (detected through file system state)
-- Cache TTL expires
 
-For manual invalidation:
-```php
-$cachedDiscoverer->clearCache();
-```
+For manual invalidation, restart your application or clear the cache directory.
 
 ## Troubleshooting
 
 ### Cache Not Working
+
 1. Verify PSR-16 SimpleCache implementation is properly installed
 2. Check cache permissions (for filesystem caches)
-3. Ensure cache TTL is appropriate for your use case
-4. Check logs for cache-related warnings
+3. Check logs for cache-related warnings
 
 ### Memory Issues
-1. Use filesystem or Redis cache instead of in-memory
-2. Reduce cache TTL
-3. Implement cache size limits in your cache implementation
-
-### Stale Cache
-1. Clear cache manually: `$cachedDiscoverer->clearCache()`
-2. Reduce cache TTL
-3. Implement cache warming strategies
-
-## Example: Complete Implementation
-
-```php
-<?php
-
-require_once __DIR__ . '/../bootstrap.php';
-
-use Mcp\Server;
-use Mcp\Server\Transport\StdioTransport;
-use Symfony\Component\Cache\Adapter\ArrayAdapter;
-use Symfony\Component\Cache\Psr16Cache;
-
-// Create cache instance
-$cache = new Psr16Cache(new ArrayAdapter());
-
-// Build server with discovery caching
-$server = Server::make()
-    ->withServerInfo('Cached Calculator', '1.0.0', 'Calculator with cached discovery')
-    ->withDiscovery(__DIR__, ['.'])
-    ->withLogger(logger())
-    ->withCache($cache) // Enable discovery caching
-    ->build();
-
-// Connect and start serving
-$server->connect(new StdioTransport());
-```
-
-## Migration Guide
-
-### From Non-Cached to Cached
-
-1. **Add cache dependency**:
-   ```bash
-   composer require symfony/cache
-   ```
-
-2. **Update server configuration**:
-   ```php
-   // Before
-   $server = Server::make()
-       ->withDiscovery(__DIR__, ['.'])
-       ->build();
-
-   // After
-   $server = Server::make()
-       ->withDiscovery(__DIR__, ['.'])
-       ->withCache(new Psr16Cache(new ArrayAdapter()))
-       ->build();
-   ```
-
-3. **No other changes required** - the API remains the same!
-
-## API Reference
-
-### DiscoveryState
-
-```php
-class DiscoveryState
-{
-    public function __construct(
-        array $tools = [],
-        array $resources = [],
-        array $prompts = [],
-        array $resourceTemplates = []
-    );
-
-    public function getTools(): array;
-    public function getResources(): array;
-    public function getPrompts(): array;
-    public function getResourceTemplates(): array;
-    public function isEmpty(): bool;
-    public function getElementCount(): int;
-    public function getElementCounts(): array;
-    public function merge(DiscoveryState $other): DiscoveryState;
-    public function toArray(): array;
-    public static function fromArray(array $data): DiscoveryState;
-}
-```
-
-### CachedDiscoverer
-
-```php
-class CachedDiscoverer
-{
-    public function __construct(
-        Discoverer $discoverer,
-        CacheInterface $cache,
-        LoggerInterface $logger,
-        int $cacheTtl = 3600
-    );
-
-    public function discover(string $basePath, array $directories, array $excludeDirs = []): DiscoveryState;
-    public function clearCache(): void;
-}
-```
-
-### ServerBuilder
-
-```php
-class ServerBuilder
-{
-    public function withCache(CacheInterface $cache): self;
-    // ... other methods
-}
-```
-
-## Conclusion
-
-Discovery caching provides significant performance improvements for MCP servers, especially in development environments and production deployments with frequent restarts. The state-based architecture ensures clean separation of concerns while maintaining backward compatibility with existing code.
 
-For more examples, see the `examples/10-cached-discovery-stdio/` directory in the SDK.
+- Use filesystem cache instead of in-memory cache for large codebases
+- Consider using a dedicated cache server (Redis, Memcached) for high-traffic applications