Implemented MCP logging specification with auto-injection #104

Adebayo120 · 2025-10-10T04:52:54Z

This PR implements the Model Context Protocol (MCP) logging specification, providing centralized logging capabilities with auto-injection support for capability handlers. This enables developers to debug across multiple MCP servers from a single client interface, addressing the challenge of distributed logging in MCP ecosystems.

Motivation and Context

Fixes #70

This implementation addresses the missing logging functionality as outlined in the MCP logging specification.

Problem solved:

Developers working with 10-15 MCP servers struggle with debugging across distributed logs
No centralized logging mechanism for MCP servers
Missing client-controlled log level filtering
No easy way to access logging within tools/resources/prompts

Key benefits:

Centralized logging: All server logs flow to the client for unified debugging
Client-controlled filtering: Clients can set log levels to reduce noise
Auto-injection: Zero-configuration logger access in capability handlers
Fallback support: Compatible with existing external PSR-3 loggers

How Has This Been Tested?

Comprehensive test coverage:

✅ 360 unit tests with 1530 assertions - all passing
✅ 0 PHPStan errors - full static analysis compliance
✅ 0 PHP CS Fixer issues - code style compliance

Test scenarios:

Auto-injection of McpLogger into tools, resources, and prompts
Client log level filtering (debug → emergency levels)
Fallback to external PSR-3 loggers when MCP transport unavailable
Notification serialization and transport integration
Error handling and graceful degradation
Builder configuration and server lifecycle integration

Working examples:

examples/stdio-logging-showcase/ - Complete demonstration of auto-injection
Updated calculator example with comprehensive logging

Breaking Changes

None. This implementation maintains full backward compatibility:

Existing servers continue to work without modification
Logging is opt-in via ->enableMcpLogging()
No changes to existing method signatures
Auto-injection only occurs when McpLogger or LoggerInterface parameters are declared

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Implementation highlights:

Core Components:

McpLogger: PSR-3 compliant logger with MCP notification transport
NotificationSender: Handles delivery of log messages to clients
SetLogLevelHandler: Processes client log level configuration requests
LoggingLevel enum: RFC-5424 compliant severity levels with indexing

Auto-injection mechanism:

#[McpTool(name: 'my_tool')]
public function myTool(string $input, McpLogger $logger): array {
    $logger->info('Tool called', ['input' => $input]);
    // Logger automatically injected - no configuration needed!
    return ['result' => 'processed'];
}

giacomomasseron · 2025-10-10T21:13:22Z

Why you use Yoda style?

Is it necessary?

Adebayo120 · 2025-10-11T07:59:27Z

I was only trying to follow the project convention and ensure the PR focuses on the feature, rather than refactoring. The Yoda style is not necessary, but that's what the project mostly uses at the moment. I believe refactoring is an implementation that is worthy of its own PR

@giacomomasseron

chr-hertel

Hi @Adebayo120 - thanks a lot for giving this a try!

I did a first round of review, and didn't tackle all yet - since this is a larger feature, i guess we will need a couple of rounds and discussions - also with @CodeWithKyrian.
Just want to be transparent about that from the start, but we'll guide you through it, if you're up for that.

Please have a look at my comments, and also have a look at the examples here with Inspector:

at first glance i found two issues here:

the logger appears as tool argument in the schema
setting a higher log level raises errors

let me know if you have some questions!

README.md

docs/mcp-logging.md

chr-hertel · 2025-10-11T22:27:48Z

examples/stdio-discovery-calculator/McpElements.php


-        return round($result, $this->config['precision']);
+        $finalResult = round($result, $this->config['precision']);
+        $logger->info('✅ Calculation completed successfully', [


Suggested change

$logger->info('✅ Calculation completed successfully', [

$logger->info('Calculation completed successfully', [

src/Capability/Logger/McpLogger.php

chr-hertel · 2025-10-11T22:31:57Z

src/Capability/Registry.php


    private ServerCapabilities $serverCapabilities;

+    private bool $loggingMessageNotificationEnabled = false;


can just be

Suggested change

private bool $loggingMessageNotificationEnabled = false;

private bool $logging = true;

and default on server side should be true

chr-hertel · 2025-10-11T22:34:28Z

src/Capability/Registry.php


+    private bool $loggingMessageNotificationEnabled = false;
+
+    private ?LoggingLevel $currentLoggingMessageNotificationLevel = null;


also good to have a shorter and with a default:

Suggested change

private ?LoggingLevel $currentLoggingMessageNotificationLevel = null;

private LoggingLevel $loggingLevel = LoggingLevel::Warning;

chr-hertel · 2025-10-11T22:36:16Z

src/Capability/Registry.php

+    /**
+     * Enables logging message notifications for this registry.
+     */
+    public function enableLoggingMessageNotification(): void
+    {
+        $this->loggingMessageNotificationEnabled = true;
+    }
+
+    /**
+     * Checks if logging message notification capability is enabled.
+     *
+     * @return bool True if logging message notification capability is enabled, false otherwise
+     */
+    public function isLoggingMessageNotificationEnabled(): bool
+    {
+        return $this->loggingMessageNotificationEnabled;
+    }
+
+    /**
+     * 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 setLoggingMessageNotificationLevel(LoggingLevel $level): void
+    {
+        $this->currentLoggingMessageNotificationLevel = $level;
+    }
+
+    /**
+     * Gets the current logging message notification level set by the client.
+     *
+     * @return LoggingLevel|null The current log level, or null if not set
+     */
+    public function getLoggingMessageNotificationLevel(): ?LoggingLevel
+    {
+        return $this->currentLoggingMessageNotificationLevel;
+    }


those methods should be shorter as well, please :)

are the necessary in the interface as well? 🤔

Adebayo120 · 2025-10-12T11:31:58Z

Going through comments and updating, thank you so much @chr-hertel

Adebayo120 · 2025-10-13T23:21:39Z

Hi @Adebayo120 - thanks a lot for giving this a try!

I did a first round of review, and didn't tackle all yet - since this is a larger feature, i guess we will need a couple of rounds and discussions - also with @CodeWithKyrian. Just want to be transparent about that from the start, but we'll guide you through it, if you're up for that.

Please have a look at my comments, and also have a look at the examples here with Inspector:

at first glance i found two issues here:

the logger appears as tool argument in the schema

setting a higher log level raises errors

let me know if you have some questions!

I have added implementation to excluded autoInjected ClientLogger
setting a higher log level raises errors: As far as I can see in the implementation, we don't throw an error when a higher log level is called; we only log a message on the server

Adebayo120 requested review from CodeWithKyrian, Nyholm and chr-hertel as code owners October 10, 2025 04:52

Adebayo120 force-pushed the feature/mcp-logging-specification branch from 34ae3c3 to 035b75e Compare October 10, 2025 05:39

Adebayo120 added 6 commits October 11, 2025 21:00

Implemented MCP logging specification with auto-injection

edc9cde

Added doc

36695ac

Modified doc

f68e110

Fixed lint issues

49ebb27

Fixed issues found in pipeline

21cf288

Fixed issue with McpLogger compatibility with LoggerInterface

30f8f42

Adebayo120 force-pushed the feature/mcp-logging-specification branch from 953aca7 to 30f8f42 Compare October 11, 2025 20:00

Updated with latest Server method interface

ec1e63b

chr-hertel requested changes Oct 11, 2025

View reviewed changes

Adebayo120 added 2 commits October 13, 2025 23:43

Exclude Auto injected client logger from generated input-schema

11e74b5

Streamlined examples/stdio-logging-showcase

997d819

Adebayo120 added 2 commits October 15, 2025 03:44

Simplified docs

5da6e21

Renamed McpLogger to ClientLogger

5bd3452

	$logger->info('✅ Calculation completed successfully', [
	$logger->info('Calculation completed successfully', [


		private ServerCapabilities $serverCapabilities;

		private bool $loggingMessageNotificationEnabled = false;

	private bool $loggingMessageNotificationEnabled = false;
	private bool $logging = true;


		private bool $loggingMessageNotificationEnabled = false;

		private ?LoggingLevel $currentLoggingMessageNotificationLevel = null;

	private ?LoggingLevel $currentLoggingMessageNotificationLevel = null;
	private LoggingLevel $loggingLevel = LoggingLevel::Warning;

Implemented MCP logging specification with auto-injection #104

Are you sure you want to change the base?

Implemented MCP logging specification with auto-injection #104

Uh oh!

Conversation

Adebayo120 commented Oct 10, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

giacomomasseron commented Oct 10, 2025

Uh oh!

Adebayo120 commented Oct 11, 2025

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chr-hertel Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chr-hertel Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

chr-hertel Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

chr-hertel Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

chr-hertel Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

Adebayo120 commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Adebayo120 commented Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Adebayo120 commented Oct 12, 2025 •

edited

Loading