Skip to content

Conversation

@CodeWithKyrian
Copy link
Contributor

@CodeWithKyrian CodeWithKyrian commented Oct 27, 2025

This PR standardizes error handling across all MCP handlers to comply with the MCP specification and provide better error visibility to clients while maintaining security.

Motivation & Context

  • MCP Specification Compliance: Tool execution errors were incorrectly returned as JSON-RPC errors instead of CallToolResult with isError=true as required by the MCP specification
  • Poor Error Visibility: Generic exception catching prevented actual error messages from reaching clients, making debugging difficult
  • Unclear docs: Documentation didn't clearly specify which exceptions developers should throw in their handlers
  • Inconsistent Patterns: Different handlers used different exception handling approaches

What's Changed

  • CallToolHandler: ToolCallException now returns Response with CallToolResult(isError=true) instead of JSON-RPC Error
  • ReadResourceHandler: ResourceReadException now forwards actual exception messages to clients
  • GetPromptHandler: PromptGetException now forwards actual exception messages to clients
  • Exception Handling: All handlers now catch only specific domain exceptions, with generic exceptions returning generic error messages
  • Documentation: Updated with explicit guidance on which exceptions to use for each handler type
  • Updated tests for both domain-specific and generic exception scenarios
  • Exception-Driven Reference Provider: ReferenceProviderInterface methods now throw ToolNotFoundException, ResourceNotFoundException, and PromptNotFoundException instead of returning null, with proper exception handling in all handlers
  • Simplified Exception Constructors: Not found exceptions now accept simple string parameters (name/URI) instead of request objects, making them more reusable across the codebase

Breaking Changes

Minor: ToolCallException, ResourceReadException and PromptGetException constructors now accept simple message strings instead of request objects. This aligns with documented usage patterns

@CodeWithKyrian CodeWithKyrian marked this pull request as draft October 28, 2025 10:08
@CodeWithKyrian CodeWithKyrian marked this pull request as ready for review October 28, 2025 15:38
@CodeWithKyrian CodeWithKyrian force-pushed the fix/standardized-error-handling-with-mcp-compliance branch from 93a3e6a to a2d5000 Compare October 30, 2025 11:32
@CodeWithKyrian CodeWithKyrian merged commit ca18caf into modelcontextprotocol:main Oct 30, 2025
10 checks passed
@CodeWithKyrian CodeWithKyrian deleted the fix/standardized-error-handling-with-mcp-compliance branch October 30, 2025 16:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants