Implemented MCP logging specification with auto-injection

Author: Adebayo120

composer.json

@@ -63,6 +63,7 @@
       "Mcp\\Example\\EnvVariables\\": "examples/env-variables/",
       "Mcp\\Example\\ExplicitRegistration\\": "examples/explicit-registration/",
       "Mcp\\Example\\SchemaShowcase\\": "examples/schema-showcase/",
+      "Mcp\\Example\\StdioLoggingShowcase\\": "examples/stdio-logging-showcase/",a
       "Mcp\\Tests\\": "tests/"
     }
   },

docs/mcp-elements.md

@@ -11,6 +11,7 @@ discovery and manual registration methods.
 - [Resources](#resources)
 - [Resource Templates](#resource-templates)
 - [Prompts](#prompts)
+- [Logging](#logging)
 - [Completion Providers](#completion-providers)
 - [Schema Generation and Validation](#schema-generation-and-validation)
 - [Discovery vs Manual Registration](#discovery-vs-manual-registration)
@@ -504,6 +505,55 @@ public function generatePrompt(string $topic, string $style): array
 
 **Recommendation**: Use `PromptGetException` when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.
 
+## Logging
+
+The SDK provides automatic logging support, handlers can receive logger instances automatically to send structured log messages to clients.
+
+### Configuration
+
+Logging is **enabled by default**. Use `disableClientLogging()` to turn it off:
+
+```php
+// Logging enabled (default)
+$server = Server::builder()->build();
+
+// Disable logging
+$server = Server::builder()
+    ->disableClientLogging()
+    ->build();
+```
+
+### Auto-injection
+
+The SDK automatically injects logger instances into handlers:
+
+```php
+use Mcp\Capability\Logger\ClientLogger;
+use Psr\Log\LoggerInterface;
+
+#[McpTool]
+public function processData(string $input, ClientLogger $logger): array {
+    $logger->info('Processing started', ['input' => $input]);
+    $logger->warning('Deprecated API used');
+    
+    // ... processing logic ...
+    
+    $logger->info('Processing completed');
+    return ['result' => 'processed'];
+}
+
+// Also works with PSR-3 LoggerInterface
+#[McpResource(uri: 'data://config')]
+public function getConfig(LoggerInterface $logger): array {
+    $logger->info('Configuration accessed');
+    return ['setting' => 'value'];
+}
+```
+
+### Log Levels
+
+The SDK supports all standard PSR-3 log levels with **warning** as the default level:
+
 ## Completion Providers
 
 Completion providers help MCP clients offer auto-completion suggestions for Resource Templates and Prompts. Unlike Tools and static Resources (which can be listed via `tools/list` and `resources/list`), Resource Templates and Prompts have dynamic parameters that benefit from completion hints.

docs/server-builder.md

@@ -577,6 +577,7 @@ $server = Server::builder()
 | `addRequestHandlers()` | handlers | Prepend multiple custom request handlers |
 | `addNotificationHandler()` | handler | Prepend a single custom notification handler |
 | `addNotificationHandlers()` | handlers | Prepend multiple custom notification handlers |
+| `disableClientLogging()` | - | Disable MCP client logging (enabled by default) |
 | `addTool()` | handler, name?, description?, annotations?, inputSchema? | Register tool |
 | `addResource()` | handler, uri, name?, description?, mimeType?, size?, annotations? | Register resource |
 | `addResourceTemplate()` | handler, uriTemplate, name?, description?, mimeType?, annotations? | Register resource template |

examples/stdio-logging-showcase/LoggingShowcaseHandlers.php

@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * 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\StdioLoggingShowcase;
+
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Capability\Logger\ClientLogger;
+
+/**
+ * Example handlers showcasing auto-injected MCP logging capabilities.
+ *
+ * This demonstrates how handlers can receive ClientLogger automatically
+ * without any manual configuration - just declare it as a parameter!
+ */
+final class LoggingShowcaseHandlers
+{
+    /**
+     * Tool that demonstrates different logging levels with auto-injected ClientLogger.
+     *
+     * @param string       $message The message to log
+     * @param string       $level   The logging level (debug, info, warning, error)
+     * @param ClientLogger $logger  Auto-injected MCP logger
+     *
+     * @return array<string, mixed>
+     */
+    #[McpTool(name: 'log_message', description: 'Demonstrates MCP logging with different levels')]
+    public function logMessage(string $message, string $level, ClientLogger $logger): array
+    {
+        $logger->info('🚀 Starting log_message tool', [
+            'requested_level' => $level,
+            'message_length' => \strlen($message),
+        ]);
+
+        switch (strtolower($level)) {
+            case 'debug':
+                $logger->debug("Debug: $message", ['tool' => 'log_message']);
+                break;
+            case 'info':
+                $logger->info("Info: $message", ['tool' => 'log_message']);
+                break;
+            case 'notice':
+                $logger->notice("Notice: $message", ['tool' => 'log_message']);
+                break;
+            case 'warning':
+                $logger->warning("Warning: $message", ['tool' => 'log_message']);
+                break;
+            case 'error':
+                $logger->error("Error: $message", ['tool' => 'log_message']);
+                break;
+            case 'critical':
+                $logger->critical("Critical: $message", ['tool' => 'log_message']);
+                break;
+            case 'alert':
+                $logger->alert("Alert: $message", ['tool' => 'log_message']);
+                break;
+            case 'emergency':
+                $logger->emergency("Emergency: $message", ['tool' => 'log_message']);
+                break;
+            default:
+                $logger->warning("Unknown level '$level', defaulting to info");
+                $logger->info("Info: $message", ['tool' => 'log_message']);
+        }
+
+        $logger->debug('log_message tool completed successfully');
+
+        return [
+            'message' => "Logged message with level: $level",
+            'logged_at' => date('Y-m-d H:i:s'),
+            'level_used' => $level,
+        ];
+    }
+}

examples/stdio-logging-showcase/server.php

@@ -0,0 +1,34 @@
+#!/usr/bin/env php
+<?php
+
+/*
+ * 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;
+
+logger()->info('Starting MCP Stdio Logging Showcase Server...');
+
+// Create server with auto-discovery of MCP capabilities and ENABLE MCP LOGGING
+$server = Server::builder()
+    ->setServerInfo('Stdio Logging Showcase', '1.0.0', 'Demonstration of auto-injected MCP logging in capability handlers.')
+    ->setContainer(container())
+    ->setLogger(logger())
+    ->setDiscovery(__DIR__, ['.'])
+    ->build();
+
+$transport = new StdioTransport(logger: logger());
+
+$server->run($transport);
+
+logger()->info('Logging Showcase Server is ready!');
+logger()->info('This example demonstrates auto-injection of ClientLogger into capability handlers.');

src/Capability/Logger/ClientLogger.php

@@ -0,0 +1,91 @@
+<?php
+
+/*
+ * 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\Capability\Logger;
+
+use Mcp\Schema\Enum\LoggingLevel;
+use Mcp\Server\NotificationSender;
+use Psr\Log\AbstractLogger;
+use Psr\Log\LoggerInterface;
+
+/**
+ * MCP-aware PSR-3 logger that sends log messages as MCP notifications.
+ *
+ * This logger implements the standard PSR-3 LoggerInterface and forwards
+ * log messages to the NotificationSender. The NotificationHandler will
+ * decide whether to actually send the notification based on capabilities.
+ *
+ * @author Adam Jamiu <[email protected]>
+ */
+final class ClientLogger extends AbstractLogger
+{
+    public function __construct(
+        private readonly NotificationSender $notificationSender,
+        private readonly ?LoggerInterface $fallbackLogger = null,
+    ) {
+    }
+
+    /**
+     * Logs with an arbitrary level.
+     *
+     * @param string|\Stringable   $message
+     * @param array<string, mixed> $context
+     */
+    public function log($level, $message, array $context = []): void
+    {
+        // Always log to fallback logger if provided (for local debugging)
+        $this->fallbackLogger?->log($level, $message, $context);
+
+        // Convert PSR-3 level to MCP LoggingLevel
+        $mcpLevel = $this->convertToMcpLevel($level);
+        if (null === $mcpLevel) {
+            return; // Unknown level, skip MCP notification
+        }
+
+        // Send MCP logging notification - let NotificationHandler decide if it should be sent
+        try {
+            $this->notificationSender->send('notifications/message', [
+                'level' => $mcpLevel->value,
+                'data' => (string) $message,
+                'logger' => $context['logger'] ?? null,
+            ]);
+        } catch (\Throwable $e) {
+            // If MCP notification fails, at least log to fallback
+            $this->fallbackLogger?->error('Failed to send MCP log notification', [
+                'original_level' => $level,
+                'original_message' => $message,
+                'error' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    /**
+     * Converts PSR-3 log level to MCP LoggingLevel.
+     *
+     * @param mixed $level PSR-3 level
+     *
+     * @return LoggingLevel|null MCP level or null if unknown
+     */
+    private function convertToMcpLevel($level): ?LoggingLevel
+    {
+        return match (strtolower((string) $level)) {
+            'emergency' => LoggingLevel::Emergency,
+            'alert' => LoggingLevel::Alert,
+            'critical' => LoggingLevel::Critical,
+            'error' => LoggingLevel::Error,
+            'warning' => LoggingLevel::Warning,
+            'notice' => LoggingLevel::Notice,
+            'info' => LoggingLevel::Info,
+            'debug' => LoggingLevel::Debug,
+            default => null,
+        };
+    }
+}

src/Capability/Registry.php

@@ -25,6 +25,7 @@
 use Mcp\Exception\PromptNotFoundException;
 use Mcp\Exception\ResourceNotFoundException;
 use Mcp\Exception\ToolNotFoundException;
+use Mcp\Schema\Enum\LoggingLevel;
 use Mcp\Schema\Page;
 use Mcp\Schema\Prompt;
 use Mcp\Schema\Resource;
@@ -61,6 +62,10 @@ final class Registry implements RegistryInterface
      */
     private array $resourceTemplates = [];
 
+    private bool $logging = true;
+
+    private LoggingLevel $loggingLevel = LoggingLevel::Warning;
+
     public function __construct(
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
         private readonly LoggerInterface $logger = new NullLogger(),
@@ -391,6 +396,46 @@ public function setDiscoveryState(DiscoveryState $state): void
         }
     }
 
+
+    /**
+     * Disable logging message notifications for this registry.
+     */
+    public function disableLogging(): void
+    {
+        $this->logging = false;
+    }
+
+    /**
+     * Checks if logging message notification capability is enabled.
+     *
+     * @return bool True if logging capability is enabled, false otherwise
+     */
+    public function isLoggingEnabled(): bool
+    {
+        return $this->logging;
+    }
+
+    /**
+     * Sets the current logging message notification level for the client.
+     *
+     * This determines which log messages should be sent to the client.
+     * Only messages at this level and higher (more severe) will be sent.
+     */
+    public function setLoggingLevel(LoggingLevel $level): void
+    {
+        $this->loggingLevel = $level;
+    }
+
+    /**
+     * Gets the current logging message notification level set by the client.
+     *
+     * @return LoggingLevel The current log level
+     */
+    public function getLoggingLevel(): LoggingLevel
+    {
+        return $this->loggingLevel;
+    }
+
     /**
      * Calculate next cursor for pagination.
      *

src/Schema/Enum/LoggingLevel.php

@@ -18,6 +18,7 @@
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
  *
  * @author Kyrian Obikwelu <[email protected]>
+ * @author Adam Jamiu <[email protected]>
  */
 enum LoggingLevel: string
 {
@@ -29,4 +30,24 @@ enum LoggingLevel: string
     case Critical = 'critical';
     case Alert = 'alert';
     case Emergency = 'emergency';
+
+    /**
+     * Gets the severity index for this log level.
+     * Higher values indicate more severe log levels.
+     *
+     * @return int Severity index (0-7, where 7 is most severe)
+     */
+    public function getSeverityIndex(): int
+    {
+        return match ($this) {
+            self::Debug => 0,
+            self::Info => 1,
+            self::Notice => 2,
+            self::Warning => 3,
+            self::Error => 4,
+            self::Critical => 5,
+            self::Alert => 6,
+            self::Emergency => 7,
+        };
+    }
 }