fix: add compatibility handling for non-standard notifications by loocor · Pull Request #247 · modelcontextprotocol/rust-sdk

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

loocor · 2025-06-05T15:14:06Z

Summary

This PR addresses the issue where the Rust SDK fails to parse messages containing non-standard notifications (like notifications/stderr from @modelcontextprotocol/server-everything ), causing connection failures and preventing proper MCP communication.

The solution implements graceful handling of non-standard notifications at the transport layer in crates/rmcp/src/transport/async_rw.rs:

Introduced is_standard_notification function to check for standard MCP notifications.
Added try_parse_with_compatibility function to handle parsing messages with compatibility for non-standard notifications.
Updated the decoder implementation to utilize the new compatibility handling.
Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

Motivation and Context

Problem: When connecting to MCP servers that send non-standard notifications (such as Claude Desktop's notifications/stderr), the Rust SDK fails to deserialize these messages, causing the entire connection to fail with parsing errors.

Root Cause: The SDK's strict adherence to the MCP specification means any non-standard notification causes a deserialization failure, breaking the communication channel.

Why This Approach: Instead of hardcoding specific non-standard notification types into the core model (which would pollute the standard and require updates for each new non-standard notification), this solution:

Preserves the purity of the MCP specification in the core model
Provides universal compatibility with any non-standard notification
Maintains forward compatibility without code changes
Follows the principle of graceful degradation

How Has This Been Tested?

Real-world scenario: Tested against Claude Desktop MCP servers that send notifications/stderr
Unit tests: Added comprehensive tests for is_standard_notification and try_parse_with_compatibility functions
Integration testing: Verified that standard notifications continue to work correctly
Edge cases: Tested with malformed JSON, mixed standard/non-standard message streams
Logging verification: Confirmed that non-standard notifications are properly logged and ignored

Breaking Changes

None. This is a backward-compatible change that:

Does not modify existing APIs or data structures
Maintains all existing functionality for standard notifications
Only adds graceful handling for previously failing scenarios

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

Design Philosophy: This solution follows the principle of "be liberal in what you accept, conservative in what you send." The SDK remains strict about outgoing messages (maintaining standard compliance) while being tolerant of incoming non-standard notifications.

Alternative Approaches Considered:

Hardcoding specific types (like PR stderr-notification-handler #149): Rejected due to poor scalability and standard pollution
Ignoring all parsing errors: Rejected as it would mask legitimate parsing issues
Configuration-based filtering: Rejected as it adds complexity without significant benefit

Implementation Notes:

The is_standard_notification function should be updated when new official notifications are added to the MCP specification
Debug logging provides visibility into ignored non-standard notifications for troubleshooting
The solution operates at the transport layer, keeping the application layer clean

Future Considerations:

Could be extended to support configurable filtering of specific non-standard notifications
Metrics could be added to track the frequency of non-standard notifications
The approach could be generalized to handle other types of non-standard messages beyond notifications

…nc_rw - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.

jokemanfire

LGTM

…nc_rw (modelcontextprotocol#247) - Introduced `is_standard_notification` function to check for standard MCP notifications. - Added `try_parse_with_compatibility` function to handle parsing messages with compatibility for non-standard notifications. - Updated the decoder implementation to utilize the new compatibility handling. - Added unit tests for standard notification checks and compatibility function to ensure correct behavior.