Merge branch 'main' into allow-runtime-tools

Author: e0ipso

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `mcp/sdk` will be documented in this file.
 
+0.6.0
+-----
+
+* Allow overriding the default name pattern for Discovery
+* Add configurable session garbage collection (`gcProbability`/`gcDivisor`)
+
 0.5.0
 -----
 

composer.json

@@ -80,7 +80,10 @@
       "Mcp\\Example\\Server\\OAuthMicrosoft\\": "examples/server/oauth-microsoft/",
       "Mcp\\Example\\Server\\SchemaShowcase\\": "examples/server/schema-showcase/",
       "Mcp\\Tests\\": "tests/"
-    }
+    },
+    "classmap": [
+      "tests/Unit/Capability/Discovery/Fixtures/AlternativeFileNameToolHandler.class.inc"
+    ]
   },
   "config": {
     "allow-plugins": {
@@ -89,4 +92,4 @@
     },
     "sort-packages": true
   }
-}
+}

docs/server-builder.md

@@ -99,8 +99,9 @@ $server = Server::builder()
     ->setDiscovery(
         basePath: __DIR__,
         scanDirs: ['.', 'src', 'lib'],           // Where to look for MCP attributes
-        excludeDirs: ['vendor', 'tests'],        // Where NOT to look 
-        cache: $cacheInstance                    // Optional: cache discovered elements
+        excludeDirs: ['vendor', 'tests'],        // Where NOT to look
+        cache: $cacheInstance,                   // Optional: cache discovered elements
+        namePatterns: ['*.php', '*.inc'],        // Optional: list of filename patterns to match
     );
 ```
 
@@ -109,6 +110,7 @@ $server = Server::builder()
 - `$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
+- `$namePatterns` (array): Optional list of patterns (regexp, glob, or string) for file names (default: `['*.php']`)
 
 **Basic Discovery (scans current directory and `src/`):**
 ```php
@@ -137,7 +139,7 @@ $server = Server::builder()
 
 **How `excludeDirs` works:**
 - If scanning `src/` and there's `src/vendor/`, it will be excluded
-- If scanning `lib/` and there's `lib/tests/`, it will be excluded  
+- If scanning `lib/` and there's `lib/tests/`, it will be excluded
 - But if `vendor/` and `tests/` are at the same level as `src/`, they're not scanned anyway (not in `scanDirs`)
 
 > **Performance**: Always use a cache in production. The first run scans and caches all discovered MCP elements, making
@@ -154,11 +156,6 @@ use Mcp\Server\Session\Psr16SessionStore;
 use Symfony\Component\Cache\Psr16Cache;
 use Symfony\Component\Cache\Adapter\RedisAdapter;
 
-// Use default in-memory sessions with custom TTL
-$server = Server::builder()
-    ->setSession(ttl: 7200) // 2 hours
-    ->build();
-
 // Override with file-based storage
 $server = Server::builder()
     ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
@@ -186,6 +183,45 @@ $server = Server::builder()
     ->build();
 ```
 
+### Garbage Collection Configuration
+
+The SDK periodically runs garbage collection to clean up expired sessions, similar to PHP's native
+`session.gc_probability` and `session.gc_divisor` settings. The probability that GC runs on any given
+request is `gcProbability / gcDivisor`.
+
+```php
+// Default: 1/100 (1% chance per request)
+$server = Server::builder()
+    ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
+    ->build();
+
+// Higher frequency: 1/10 (10% chance per request)
+$server = Server::builder()
+    ->setSession(
+        new FileSessionStore(__DIR__ . '/sessions'),
+        gcProbability: 1,
+        gcDivisor: 10,
+    )
+    ->build();
+
+// Run GC on every request
+$server = Server::builder()
+    ->setSession(gcProbability: 1, gcDivisor: 1)
+    ->build();
+
+// Disable GC entirely (e.g. when using an external cleanup process)
+$server = Server::builder()
+    ->setSession(gcProbability: 0)
+    ->build();
+```
+
+**Parameters:**
+- `$gcProbability` (int): The numerator of the GC probability fraction (default: `1`). Set to `0` to disable GC.
+- `$gcDivisor` (int): The denominator of the GC probability fraction (default: `100`). Must be >= 1.
+
+> **Note**: When providing a custom `SessionManagerInterface` via the `$sessionManager` parameter,
+> the `gcProbability` and `gcDivisor` settings are ignored — you control GC behavior in your own implementation.
+
 **Available Session Stores:**
 - `InMemorySessionStore`: Fast in-memory storage (default)
 - `FileSessionStore`: Persistent file-based storage
@@ -255,19 +291,19 @@ $server = Server::builder()
         name: 'add_numbers',
         description: 'Adds two numbers together'
     )
-    
+
     // Using class method pair
     ->addTool(
         handler: [Calculator::class, 'multiply'],
         name: 'multiply_numbers'
         // name and description are optional - derived from method name and docblock
     )
-    
+
     // Using instance method
     ->addTool(
         handler: [$calculatorInstance, 'divide']
     )
-    
+
     // Using invokable class
     ->addTool(
         handler: InvokableCalculator::class
@@ -482,17 +518,17 @@ $server = Server::builder()
 individual JSON-RPC messages. They do not receive the builder's registry, container, or discovery output unless you pass
 those dependencies in yourself.
 
-> **Warning**: Custom message handlers bypass discovery, manual capability registration, and container lookups (unless 
+> **Warning**: Custom message handlers bypass discovery, manual capability registration, and container lookups (unless
 > you explicitly pass them). Tools, resources, and prompts you register elsewhere will not show up unless your handler
-> loads and executes them manually. Reach for this API only when you need that level of control and are comfortable 
+> loads and executes them manually. Reach for this API only when you need that level of control and are comfortable
 > taking on the additional plumbing.
 
 ### Request Handlers
 
-Handle JSON-RPC requests (messages with an `id` that expect a response). Request handlers **must** return either a 
+Handle JSON-RPC requests (messages with an `id` that expect a response). Request handlers **must** return either a
 `Response` or an `Error` object.
 
-Attach request handlers with `addRequestHandler()` (single) or `addRequestHandlers()` (multiple). You can call these 
+Attach request handlers with `addRequestHandler()` (single) or `addRequestHandlers()` (multiple). You can call these
 methods as many times as needed; each call prepends the handlers so they execute before the defaults:
 
 ```php
@@ -569,7 +605,7 @@ interface NotificationHandlerInterface
 
 ### Example
 
-Check out `examples/custom-method-handlers/server.php` for a complete example showing how to implement 
+Check out `examples/custom-method-handlers/server.php` for a complete example showing how to implement
 custom `tools/list` and `tools/call` request handlers independently of the registry.
 
 ## Complete Example
@@ -601,25 +637,25 @@ $container->set(DatabaseService::class, new DatabaseService($container->get(\PDO
 $server = Server::builder()
     // Server identity
     ->setServerInfo('Advanced Calculator', '2.1.0')
-    
+
     // Performance and behavior
     ->setPaginationLimit(100)
     ->setInstructions('Use calculate tool for math operations. Check config resource for current settings.')
-    
+
     // Discovery with caching
     ->setDiscovery(__DIR__, ['src'], ['vendor', 'tests'], $cache)
-    
+
     // Session management
     ->setSession($sessionStore)
-    
+
     // Services
     ->setLogger($logger)
     ->setContainer($container)
-    
+
     // Manual capability registration
     ->addTool([Calculator::class, 'advancedCalculation'], 'advanced_calc')
     ->addResource([Config::class, 'getSettings'], 'config://app/settings', 'app_settings')
-    
+
     // Build the server
     ->build();
 ```
@@ -632,7 +668,7 @@ $server = Server::builder()
 | `setPaginationLimit()` | limit | Set max items per page |
 | `setInstructions()` | instructions | Set usage instructions |
 | `setDiscovery()` | basePath, scanDirs?, excludeDirs?, cache? | Configure attribute discovery |
-| `setSession()` | store?, factory?, ttl? | Configure session management |
+| `setSession()` | sessionStore?, sessionManager?, gcProbability?, gcDivisor? | Configure session management |
 | `setLogger()` | logger | Set PSR-3 logger |
 | `setContainer()` | container | Set PSR-11 container |
 | `setEventDispatcher()` | dispatcher | Set PSR-14 event dispatcher |

src/Capability/Discovery/CachedDiscoverer.php

@@ -38,11 +38,12 @@ public function __construct(
     /**
      * Discover MCP elements in the specified directories with caching.
      *
-     * @param string        $basePath    the base path for resolving directories
-     * @param array<string> $directories list of directories (relative to base path) to scan
-     * @param array<string> $excludeDirs list of directories (relative to base path) to exclude from the scan
+     * @param string        $basePath     the base path for resolving directories
+     * @param array<string> $directories  list of directories (relative to base path) to scan
+     * @param array<string> $excludeDirs  list of directories (relative to base path) to exclude from the scan
+     * @param array<string> $namePatterns list of file name patterns for the scan. Compatible with Finder->name()
      */
-    public function discover(string $basePath, array $directories, array $excludeDirs = []): DiscoveryState
+    public function discover(string $basePath, array $directories, array $excludeDirs = [], array $namePatterns = self::DEFAULT_NAME_PATERNS): DiscoveryState
     {
         $cacheKey = $this->generateCacheKey($basePath, $directories, $excludeDirs);
 
@@ -63,7 +64,7 @@ public function discover(string $basePath, array $directories, array $excludeDir
             'directories' => $directories,
         ]);
 
-        $discoveryState = $this->discoverer->discover($basePath, $directories, $excludeDirs);
+        $discoveryState = $this->discoverer->discover($basePath, $directories, $excludeDirs, $namePatterns);
 
         $this->cache->set($cacheKey, $discoveryState);
 

src/Capability/Discovery/Discoverer.php

@@ -65,11 +65,12 @@ public function __construct(
     /**
      * Discover MCP elements in the specified directories and return the discovery state.
      *
-     * @param string        $basePath    the base path for resolving directories
-     * @param array<string> $directories list of directories (relative to base path) to scan
-     * @param array<string> $excludeDirs list of directories (relative to base path) to exclude from the scan
+     * @param string        $basePath     the base path for resolving directories
+     * @param array<string> $directories  list of directories (relative to base path) to scan
+     * @param array<string> $excludeDirs  list of directories (relative to base path) to exclude from the scan
+     * @param array<string> $namePatterns list of file name patterns for the scan. Compatible with Finder->name()
      */
-    public function discover(string $basePath, array $directories, array $excludeDirs = []): DiscoveryState
+    public function discover(string $basePath, array $directories, array $excludeDirs = [], array $namePatterns = self::DEFAULT_NAME_PATERNS): DiscoveryState
     {
         $startTime = microtime(true);
         $discoveredCount = [
@@ -79,6 +80,8 @@ public function discover(string $basePath, array $directories, array $excludeDir
             'resourceTemplates' => 0,
         ];
 
+        $namePatterns = !empty($namePatterns) ? $namePatterns : self::DEFAULT_NAME_PATERNS;
+
         $tools = [];
         $resources = [];
         $prompts = [];
@@ -106,15 +109,14 @@ public function discover(string $basePath, array $directories, array $excludeDir
             $finder->files()
                 ->in($absolutePaths)
                 ->exclude($excludeDirs)
-                ->name('*.php');
+                ->name($namePatterns);
 
             foreach ($finder as $file) {
                 $this->processFile($file, $discoveredCount, $tools, $resources, $prompts, $resourceTemplates);
             }
         } catch (\Throwable $e) {
             $this->logger->error('Error during file finding process for MCP discovery'.json_encode($e->getTrace(), \JSON_PRETTY_PRINT), [
                 'exception' => $e,
-                'trace' => $e->getTraceAsString(),
             ]);
         }
 
@@ -196,7 +198,6 @@ private function processFile(SplFileInfo $file, array &$discoveredCount, array &
                 'file' => $file->getPathname(),
                 'class' => $className,
                 'exception' => $e,
-                'trace' => $e->getTraceAsString(),
             ]);
         }
     }
@@ -297,9 +298,15 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
                     break;
             }
         } catch (ExceptionInterface $e) {
-            $this->logger->error("Failed to process MCP attribute on {$className}::{$methodName}", ['attribute' => $attributeClassName, 'exception' => $e, 'trace' => $e->getPrevious() ? $e->getPrevious()->getTraceAsString() : $e->getTraceAsString()]);
+            $this->logger->error("Failed to process MCP attribute on {$className}::{$methodName}", [
+                'attribute' => $attributeClassName,
+                'exception' => $e,
+            ]);
         } catch (\Throwable $e) {
-            $this->logger->error("Unexpected error processing attribute on {$className}::{$methodName}", ['attribute' => $attributeClassName, 'exception' => $e, 'trace' => $e->getTraceAsString()]);
+            $this->logger->error("Unexpected error processing attribute on {$className}::{$methodName}", [
+                'attribute' => $attributeClassName,
+                'exception' => $e,
+            ]);
         }
     }
 

src/Capability/Discovery/DiscovererInterface.php

@@ -20,12 +20,15 @@
  */
 interface DiscovererInterface
 {
+    public const DEFAULT_NAME_PATERNS = ['*.php'];
+
     /**
      * Discover MCP elements in the specified directories and return the discovery state.
      *
-     * @param string        $basePath    the base path for resolving directories
-     * @param array<string> $directories list of directories (relative to base path) to scan
-     * @param array<string> $excludeDirs list of directories (relative to base path) to exclude from the scan
+     * @param string        $basePath     the base path for resolving directories
+     * @param array<string> $directories  list of directories (relative to base path) to scan
+     * @param array<string> $excludeDirs  list of directories (relative to base path) to exclude from the scan
+     * @param array<string> $namePatterns list of file name patterns for the scan. Compatible with Finder->name()
      */
-    public function discover(string $basePath, array $directories, array $excludeDirs = []): DiscoveryState;
+    public function discover(string $basePath, array $directories, array $excludeDirs = [], array $namePatterns = self::DEFAULT_NAME_PATERNS): DiscoveryState;
 }

src/Capability/Discovery/DocBlockParser.php

@@ -47,8 +47,7 @@ public function parseDocBlock(string|false|null $docComment): ?DocBlock
         } catch (\Throwable $e) {
             // Log error or handle gracefully if invalid DocBlock syntax is encountered
             $this->logger->warning('Failed to parse DocBlock', [
-                'error' => $e->getMessage(),
-                'exception_trace' => $e->getTraceAsString(),
+                'exception' => $e,
             ]);
 
             return null;

src/Capability/Discovery/SchemaGenerator.php

@@ -374,7 +374,8 @@ private function applyEnumConstraints(array $paramSchema, array $paramInfo): arr
 
             if ($jsonBackingType) {
                 if (isset($paramSchema['type']) && \is_array($paramSchema['type']) && \in_array('null', $paramSchema['type'])) {
-                    $paramSchema['type'] = ['null', $jsonBackingType];
+                    $paramSchema['type'] = [$jsonBackingType, 'null'];
+                    $paramSchema['enum'][] = null;
                 } else {
                     $paramSchema['type'] = $jsonBackingType;
                 }
@@ -383,7 +384,8 @@ private function applyEnumConstraints(array $paramSchema, array $paramInfo): arr
             // Non-backed enum - use names as enum values
             $paramSchema['enum'] = array_column($enumClass::cases(), 'name');
             if (isset($paramSchema['type']) && \is_array($paramSchema['type']) && \in_array('null', $paramSchema['type'])) {
-                $paramSchema['type'] = ['null', 'string'];
+                $paramSchema['type'] = ['string', 'null'];
+                $paramSchema['enum'][] = null;
             } else {
                 $paramSchema['type'] = 'string';
             }

src/Capability/Discovery/SchemaValidator.php

@@ -87,8 +87,7 @@ public function validateAgainstJsonSchema(mixed $data, array|object $schema): ar
             $result = $validator->validate($dataToValidate, $schemaObject);
         } catch (\Throwable $e) {
             $this->logger->error('MCP SDK: JSON Schema validation failed internally.', [
-                'exception_message' => $e->getMessage(),
-                'exception_trace' => $e->getTraceAsString(),
+                'exception' => $e,
                 'data' => json_encode($dataToValidate),
                 'schema' => json_encode($schemaObject),
             ]);

src/Capability/Registry/Loader/DiscoveryLoader.php

@@ -24,18 +24,20 @@ final class DiscoveryLoader implements LoaderInterface
     /**
      * @param string[]       $scanDirs
      * @param array|string[] $excludeDirs
+     * @param string[]       $namePatterns
      */
     public function __construct(
         private string $basePath,
         private array $scanDirs,
         private array $excludeDirs,
         private DiscovererInterface $discoverer,
+        private array $namePatterns = DiscovererInterface::DEFAULT_NAME_PATERNS,
     ) {
     }
 
     public function load(RegistryInterface $registry): void
     {
-        $discoveryState = $this->discoverer->discover($this->basePath, $this->scanDirs, $this->excludeDirs);
+        $discoveryState = $this->discoverer->discover($this->basePath, $this->scanDirs, $this->excludeDirs, $this->namePatterns);
 
         $registry->setDiscoveryState($discoveryState);
     }