feat(core): Add manual registration and invokable class discovery

Implements several enhancements to the MCP server:

- Adds manual registration methods to the `Server` class (`withTool`, `withResource`, `withPrompt`, `withResourceTemplate`), allowing programmatic definition of MCP elements alongside attribute discovery. Supports array `[Class::class, 'method']` and invokable class string handlers.

- Enables the `Discoverer` to find `#[Mcp*]` attributes placed directly on invokable classes (classes with a public `__invoke` method). Attributes (`McpTool`, `McpResource`, etc.) updated accordingly.

- Refactors dependency injection within the `Server`. Core components like `Processor`, `Discoverer`, `Registry`, and `TransportState` now resolve dependencies (Logger, Cache, Config) Just-In-Time from the PSR-11 container.
  - Clarifies behavior: `withLogger/Cache/Config` methods primarily affect the default `BasicContainer`. When a custom container is used via `withContainer`, these services MUST be registered directly in the custom container.

- Adds configuration options to control discovery paths (`withBasePath`, `withScanDirectories`, `withExcludeDirectories`).

- Updates `README.md` extensively to document these new features and the updated DI behavior.

- Adds comprehensive tests for manual registration and invokable class discovery, and updates existing tests to reflect the DI refactoring.

BREAKING CHANGE: The dependency injection mechanism within the `Server` has been refactored. Components now resolve PSR-3/11/16 dependencies JIT from the container. Users providing a custom container via `withContainer()` MUST ensure `LoggerInterface`, `CacheInterface`, and `ConfigurationRepositoryInterface` are registered. The behavior of `withLogger()`, `withCache()`, and `withConfig()` is altered when a custom container is present; configuration should happen directly within the custom container itself. TransportHandler constructors now primarily accept the `Server` instance.

Author: CodeWithKyrian

.gitignore

@@ -61,4 +61,7 @@ workbench
 playground
 
 # Log files
-*.log
+*.log
+
+# Cache files
+cache

README.md

@@ -19,10 +19,12 @@
 
 // --- MCP Server Setup ---
 $logger = new StreamLogger(__DIR__.'/vanilla_server.log', 'debug');
-$server = Server::make()->withLogger($logger)->withBasePath(__DIR__)->discover();
-$processor = $server->getProcessor();
-$state = $server->getStateManager();
-$httpHandler = new HttpTransportHandler($processor, $state, $logger);
+$server = Server::make()
+    ->withLogger($logger)
+    ->withBasePath(__DIR__)
+    ->discover();
+
+$httpHandler = new HttpTransportHandler($server);
 
 // --- Basic Routing & Client ID ---
 $method = $_SERVER['REQUEST_METHOD'] ?? 'GET';

samples/php_http/server.php

@@ -4,6 +4,7 @@
 
 use PhpMcp\Server\Defaults\StreamLogger;
 use PhpMcp\Server\Server;
+use Test\SampleMcpElements;
 
 // --- Instructions ---
 // 1. composer install
@@ -24,8 +25,10 @@
 $logger = new StreamLogger(__DIR__.'/mcp.log', 'debug');
 
 $server = Server::make()
-    ->withLogger($logger)
     ->withBasePath(__DIR__)
+    ->withLogger($logger)
+    ->withTool([SampleMcpElements::class, 'simpleTool'], 'greeter')
+    ->withResource([SampleMcpElements::class, 'getUserData'], 'user://data')
     ->discover();
 
 $exitCode = $server->run('stdio');

samples/php_stdio/server.php

@@ -7,7 +7,6 @@
 use PhpMcp\Server\Transports\ReactPhpHttpTransportHandler;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use React\EventLoop\Loop;
 use React\Http\HttpServer;
 use React\Http\Message\Response;
 use React\Promise\Promise;
@@ -34,10 +33,7 @@
     ->withBasePath(__DIR__)
     ->discover();
 
-$processor = $server->getProcessor();
-$state = $server->getStateManager();
-
-$transportHandler = new ReactPhpHttpTransportHandler($processor, $state, $logger, Loop::get());
+$transportHandler = new ReactPhpHttpTransportHandler($server);
 
 // --- ReactPHP HTTP Server Setup ---
 $postEndpoint = '/mcp/message';

samples/reactphp_http/server.php

@@ -8,7 +8,7 @@
  * Marks a PHP method as an MCP Prompt generator.
  * The method should return the prompt messages, potentially using arguments for templating.
  */
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class McpPrompt
 {
     /**
@@ -18,6 +18,5 @@ final class McpPrompt
     public function __construct(
         public ?string $name = null,
         public ?string $description = null,
-    ) {
-    }
+    ) {}
 }

src/Attributes/McpPrompt.php

@@ -8,7 +8,7 @@
  * Marks a PHP class as representing or handling a specific MCP Resource instance.
  * Used primarily for the 'resources/list' discovery.
  */
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class McpResource
 {
     /**
@@ -17,15 +17,14 @@ final class McpResource
      * @param  ?string  $description  An optional description of the resource. Defaults to class DocBlock summary.
      * @param  ?string  $mimeType  The MIME type, if known and constant for this resource.
      * @param  ?int  $size  The size in bytes, if known and constant.
-     * @param  ?array<string, mixed>  $annotations  Optional annotations following the MCP spec (e.g., ['audience' => ['user'], 'priority' => 0.5]).
+     * @param  array<string, mixed>  $annotations  Optional annotations following the MCP spec (e.g., ['audience' => ['user'], 'priority' => 0.5]).
      */
     public function __construct(
         public string $uri,
         public ?string $name = null,
         public ?string $description = null,
         public ?string $mimeType = null,
         public ?int $size = null,
-        public ?array $annotations = null,
-    ) {
-    }
+        public array $annotations = [],
+    ) {}
 }

src/Attributes/McpResource.php

@@ -8,22 +8,21 @@
  * Marks a PHP class definition as representing an MCP Resource Template.
  * This is informational, used for 'resources/templates/list'.
  */
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class McpResourceTemplate
 {
     /**
      * @param  string  $uriTemplate  The URI template string (RFC 6570).
      * @param  ?string  $name  A human-readable name for the template type.  If null, a default might be generated from the method name.
      * @param  ?string  $description  Optional description. Defaults to class DocBlock summary.
      * @param  ?string  $mimeType  Optional default MIME type for matching resources.
-     * @param  ?array<string, mixed>  $annotations  Optional annotations following the MCP spec.
+     * @param  array<string, mixed>  $annotations  Optional annotations following the MCP spec.
      */
     public function __construct(
         public string $uriTemplate,
         public ?string $name = null,
         public ?string $description = null,
         public ?string $mimeType = null,
-        public ?array $annotations = null,
-    ) {
-    }
+        public array $annotations = [],
+    ) {}
 }

src/Attributes/McpResourceTemplate.php

@@ -4,7 +4,7 @@
 
 use Attribute;
 
-#[Attribute(Attribute::TARGET_METHOD)]
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 class McpTool
 {
     /**
@@ -14,6 +14,5 @@ class McpTool
     public function __construct(
         public ?string $name = null,
         public ?string $description = null,
-    ) {
-    }
+    ) {}
 }