refactor(Server): Decouple discovery from build and refine core components

- ServerBuilder no longer configures discovery paths or runs discovery automatically during build; discovery is now an explicit step via `Server->discover()`.
- `Server::discover()` now accepts path configurations, clears only discovered/cached elements (preserving manual ones), and saves only discovered elements to cache.
- `Registry` distinguishes between manually registered and discovered elements:
    - Manual registrations take precedence over discovered/cached elements with the same identifier.
    - Caching methods (`loadDiscoveredElementsFromCache`, `saveDiscoveredElementsToCache`, `clearDiscoveredElements`) now operate only on discovered elements.
- `ClientStateManager` constructor defaults to `ArrayCache` if no PSR-16 cache is provided, ensuring basic stateful functionality.
- `ClientStateManager` now stores client-requested log levels.
- `Processor` updated to use `ClientStateManager` for persisting client-requested log levels and relies on `Configuration` VO for server capabilities.
- `JsonRpc\Response` constructor and `fromArray` updated to correctly handle `null` IDs for error responses as per JSON-RPC 2.0 spec, fixing related TypeErrors.
- `StdioServerTransport` constructor now accepts optional input/output stream resources, improving testability and flexibility.
- `HttpServerTransport` POST message handling reverted to synchronous body reading (`getBody()->getContents()`) for reliability with current `react/http` behavior, resolving hangs.
- Corrected `Support\DocBlockParser` and `Support\Discoverer` constructors to directly accept `LoggerInterface` instead of `ContainerInterface`.
- Updated unit tests for `ServerBuilder`, `Server`, `Registry`, `ClientStateManager`, `StdioServerTransport`, `HttpServerTransport`, `ProtocolHandler`, and JSON-RPC classes to reflect architectural changes and improve reliability, including fixes for Mockery state and loop interactions.
- Renamed `Server::getProtocolHandler()` to `Server::getProtocol()` and updated relevant class names (`ProtocolHandler` to `Protocol`).
- Renamed `Server::isLoaded()` in Registry to `discoveryRanOrCached()`.
- Renamed examples and updated their internal scripts and documentation comments to reflect new server API and best practices.
- Added more examples to showcase other use cases of the library

Author: CodeWithKyrian

examples/standalone_stdio_calculator/McpElements.php renamed to examples/01-discovery-stdio-calculator/McpElements.php

@@ -0,0 +1,82 @@
+#!/usr/bin/env php
+<?php
+
+/*
+    |--------------------------------------------------------------------------
+    | MCP Stdio Calculator Server (Attribute Discovery)
+    |--------------------------------------------------------------------------
+    |
+    | This server demonstrates using attribute-based discovery to find MCP
+    | elements (Tools, Resources) in the 'McpElements.php' file within this
+    | directory. It runs via the STDIO transport.
+    |
+    | To Use:
+    | 1. Ensure 'McpElements.php' defines classes with MCP attributes.
+    | 2. Configure your MCP Client (e.g., Cursor) for this server:
+    |
+    | {
+    |     "mcpServers": {
+    |         "php-stdio-calculator": {
+    |             "command": "php",
+    |             "args": ["/full/path/to/examples/01-discovery-stdio-calculator/server.php"]
+    |         }
+    |     }
+    | }
+    |
+    | The ServerBuilder builds the server instance, then $server->discover()
+    | scans the current directory (specified by basePath: __DIR__, scanDirs: ['.'])
+    | to find and register elements before listening on STDIN/STDOUT.
+    |
+    | If you provided a `CacheInterface` implementation to the ServerBuilder,
+    | the discovery process will be cached, so you can comment out the
+    | discovery call after the first run to speed up subsequent runs.
+    |
+*/
+declare(strict_types=1);
+
+chdir(__DIR__);
+require_once '../../vendor/autoload.php';
+require_once 'McpElements.php';
+
+use PhpMcp\Server\Server;
+use PhpMcp\Server\Transports\StdioServerTransport;
+use Psr\Log\AbstractLogger;
+
+class StderrLogger extends AbstractLogger
+{
+    public function log($level, \Stringable|string $message, array $context = []): void
+    {
+        fwrite(STDERR, sprintf(
+            "[%s] %s %s\n",
+            strtoupper($level),
+            $message,
+            empty($context) ? '' : json_encode($context)
+        ));
+    }
+}
+
+try {
+    $logger = new StderrLogger;
+    $logger->info('Starting MCP Stdio Calculator Server...');
+
+    $server = Server::make()
+        ->withServerInfo('Stdio Calculator', '1.1.0')
+        ->withLogger($logger)
+        ->build();
+
+    $server->discover(__DIR__, ['.']);
+
+    $transport = new StdioServerTransport;
+
+    $server->listen($transport);
+
+    $logger->info('Server listener stopped gracefully.');
+    exit(0);
+
+} catch (\Throwable $e) {
+    fwrite(STDERR, "[MCP SERVER CRITICAL ERROR]\n");
+    fwrite(STDERR, 'Error: '.$e->getMessage()."\n");
+    fwrite(STDERR, 'File: '.$e->getFile().':'.$e->getLine()."\n");
+    fwrite(STDERR, $e->getTraceAsString()."\n");
+    exit(1);
+}

examples/01-discovery-stdio-calculator/server.php

@@ -1,6 +1,39 @@
 #!/usr/bin/env php
 <?php
 
+/*
+    |--------------------------------------------------------------------------
+    | MCP HTTP User Profile Server (Attribute Discovery)
+    |--------------------------------------------------------------------------
+    |
+    | This server demonstrates attribute-based discovery for MCP elements
+    | (ResourceTemplates, Resources, Tools, Prompts) defined in 'McpElements.php'.
+    | It runs via the HTTP transport, listening for SSE and POST requests.
+    |
+    | To Use:
+    | 1. Ensure 'McpElements.php' defines classes with MCP attributes.
+    | 2. Run this script from your CLI: `php server.php`
+    |    The server will listen on http://127.0.0.1:8080 by default.
+    | 3. Configure your MCP Client (e.g., Cursor) for this server:
+    |
+    | {
+    |     "mcpServers": {
+    |         "php-http-userprofile": {
+    |             "url": "http://127.0.0.1:8080/mcp/sse" // Use the SSE endpoint
+    |             // Ensure your client can reach this address
+    |         }
+    |     }
+    | }
+    |
+    | The ServerBuilder builds the server, $server->discover() scans for elements,
+    | and then $server->listen() starts the ReactPHP HTTP server.
+    |
+    | If you provided a `CacheInterface` implementation to the ServerBuilder,
+    | the discovery process will be cached, so you can comment out the
+    | discovery call after the first run to speed up subsequent runs.
+    |
+*/
+
 declare(strict_types=1);
 
 chdir(__DIR__);
@@ -22,11 +55,11 @@ public function log($level, \Stringable|string $message, array $context = []): v
 }
 
 try {
-    $logger = new StderrLogger();
+    $logger = new StderrLogger;
     $logger->info('Starting MCP HTTP User Profile Server...');
 
     // --- Setup DI Container for DI in McpElements class ---
-    $container = new BasicContainer();
+    $container = new BasicContainer;
     $container->set(LoggerInterface::class, $logger);
 
     $server = Server::make()

examples/standalone_http_userprofile/McpElements.php renamed to examples/02-discovery-http-userprofile/McpElements.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Mcp\ManualStdioExample;
+
+use Psr\Log\LoggerInterface;
+
+class SimpleHandlers
+{
+    private LoggerInterface $logger;
+
+    private string $appVersion = '1.0-manual';
+
+    public function __construct(LoggerInterface $logger)
+    {
+        $this->logger = $logger;
+        $this->logger->info('SimpleHandlers instantiated for manual registration example.');
+    }
+
+    /**
+     * A manually registered tool to echo input.
+     *
+     * @param  string  $text  The text to echo.
+     * @return string The echoed text.
+     */
+    public function echoText(string $text): string
+    {
+        $this->logger->info("Manual tool 'echo_text' called.", ['text' => $text]);
+
+        return 'Echo: '.$text;
+    }
+
+    /**
+     * A manually registered resource providing app version.
+     *
+     * @return string The application version.
+     */
+    public function getAppVersion(): string
+    {
+        $this->logger->info("Manual resource 'app://version' read.");
+
+        return $this->appVersion;
+    }
+
+    /**
+     * A manually registered prompt template.
+     *
+     * @param  string  $userName  The name of the user.
+     * @return array The prompt messages.
+     */
+    public function greetingPrompt(string $userName): array
+    {
+        $this->logger->info("Manual prompt 'personalized_greeting' called.", ['userName' => $userName]);
+
+        return [
+            ['role' => 'user', 'content' => "Craft a personalized greeting for {$userName}."],
+        ];
+    }
+
+    /**
+     * A manually registered resource template.
+     *
+     * @param  string  $itemId  The ID of the item.
+     * @return array Item details.
+     */
+    public function getItemDetails(string $itemId): array
+    {
+        $this->logger->info("Manual template 'item://{itemId}' resolved.", ['itemId' => $itemId]);
+
+        return ['id' => $itemId, 'name' => "Item {$itemId}", 'description' => "Details for item {$itemId} from manual template."];
+    }
+}

examples/standalone_http_userprofile/server.php renamed to examples/02-discovery-http-userprofile/server.php

@@ -0,0 +1,79 @@
+#!/usr/bin/env php
+<?php
+
+/*
+    |--------------------------------------------------------------------------
+    | MCP Stdio Server (Manual Element Registration)
+    |--------------------------------------------------------------------------
+    |
+    | This server demonstrates how to manually register all MCP elements
+    | (Tools, Resources, Prompts, ResourceTemplates) using the ServerBuilder's
+    | fluent `withTool()`, `withResource()`, etc., methods.
+    | It does NOT use attribute discovery. Handlers are in 'SimpleHandlers.php'.
+    | It runs via the STDIO transport.
+    |
+    | To Use:
+    | 1. Configure your MCP Client (e.g., Cursor) for this server:
+    |
+    | {
+    |     "mcpServers": {
+    |         "php-stdio-manual": {
+    |             "command": "php",
+    |             "args": ["/full/path/to/examples/03-manual-registration-stdio/server.php"]
+    |         }
+    |     }
+    | }
+    |
+    | All elements are explicitly defined during the ServerBuilder chain.
+    | The $server->discover() method is NOT called.
+    |
+*/
+
+declare(strict_types=1);
+
+chdir(__DIR__);
+require_once '../../vendor/autoload.php';
+require_once './SimpleHandlers.php';
+
+use Mcp\ManualStdioExample\SimpleHandlers;
+use PhpMcp\Server\Defaults\BasicContainer;
+use PhpMcp\Server\Server;
+use PhpMcp\Server\Transports\StdioServerTransport;
+use Psr\Log\AbstractLogger;
+use Psr\Log\LoggerInterface;
+
+class StderrLogger extends AbstractLogger
+{
+    public function log($level, \Stringable|string $message, array $context = []): void
+    {
+        fwrite(STDERR, sprintf("[%s][%s] %s %s\n", date('Y-m-d H:i:s'), strtoupper($level), $message, empty($context) ? '' : json_encode($context)));
+    }
+}
+
+try {
+    $logger = new StderrLogger;
+    $logger->info('Starting MCP Manual Registration (Stdio) Server...');
+
+    $container = new BasicContainer;
+    $container->set(LoggerInterface::class, $logger);
+
+    $server = Server::make()
+        ->withServerInfo('Manual Reg Server', '1.0.0')
+        ->withLogger($logger)
+        ->withContainer($container)
+        ->withTool([SimpleHandlers::class, 'echoText'], 'echo_text')
+        ->withResource([SimpleHandlers::class, 'getAppVersion'], 'app://version', 'application_version', mimeType: 'text/plain')
+        ->withPrompt([SimpleHandlers::class, 'greetingPrompt'], 'personalized_greeting')
+        ->withResourceTemplate([SimpleHandlers::class, 'getItemDetails'], 'item://{itemId}/details', 'get_item_details', mimeType: 'application/json')
+        ->build();
+
+    $transport = new StdioServerTransport;
+    $server->listen($transport);
+
+    $logger->info('Server listener stopped gracefully.');
+    exit(0);
+
+} catch (\Throwable $e) {
+    fwrite(STDERR, "[MCP SERVER CRITICAL ERROR]\n".$e."\n");
+    exit(1);
+}

examples/03-manual-registration-stdio/SimpleHandlers.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Mcp\CombinedHttpExample\Discovered;
+
+use PhpMcp\Server\Attributes\McpResource;
+use PhpMcp\Server\Attributes\McpTool;
+
+class DiscoveredElements
+{
+    /**
+     * A tool discovered via attributes.
+     *
+     * @return string A status message.
+     */
+    #[McpTool(name: 'discovered_status_check')]
+    public function checkSystemStatus(): string
+    {
+        return 'System status: OK (discovered)';
+    }
+
+    /**
+     * A resource discovered via attributes.
+     * This will be overridden by a manual registration with the same URI.
+     *
+     * @return string Content.
+     */
+    #[McpResource(uri: 'config://priority', name: 'priority_config_discovered')]
+    public function getPriorityConfigDiscovered(): string
+    {
+        return 'Discovered Priority Config: Low';
+    }
+}

examples/03-manual-registration-stdio/server.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Mcp\CombinedHttpExample\Manual;
+
+use Psr\Log\LoggerInterface;
+
+class ManualHandlers
+{
+    private LoggerInterface $logger;
+
+    public function __construct(LoggerInterface $logger)
+    {
+        $this->logger = $logger;
+    }
+
+    /**
+     * A manually registered tool.
+     *
+     * @param  string  $user  The user to greet.
+     * @return string Greeting.
+     */
+    public function manualGreeter(string $user): string
+    {
+        $this->logger->info("Manual tool 'manual_greeter' called for {$user}");
+
+        return "Hello {$user}, from manual registration!";
+    }
+
+    /**
+     * Manually registered resource that overrides a discovered one.
+     *
+     * @return string Content.
+     */
+    public function getPriorityConfigManual(): string
+    {
+        $this->logger->info("Manual resource 'config://priority' read.");
+
+        return 'Manual Priority Config: HIGH (overrides discovered)';
+    }
+}