Summary

Implements the pattern described in #2153: MCPServer users should raise exceptions to signal errors, and the framework converts them to appropriate protocol responses — without leaking internal details to clients.

Changes

Error propagation — let user-raised exceptions pass through:

• Tool.run(): ToolError and MCPError now pass through without re-wrapping (previously all exceptions were blindly wrapped as ToolError)
• FunctionResource.read(): ResourceError and MCPError pass through
• Prompt.render(): PromptError (new) and MCPError pass through

Handler-level error conversion — framework catches and converts:

• _handle_call_tool(): Explicitly catches ToolError → CallToolResult(is_error=True); unexpected exceptions get a sanitized message
• _handle_read_resource(): Catches ResourceError → MCPError(INVALID_PARAMS); unexpected exceptions → MCPError(INTERNAL_ERROR) with sanitized message
• _handle_get_prompt(): Catches PromptError → MCPError(INVALID_PARAMS); unexpected exceptions → MCPError(INTERNAL_ERROR) with sanitized message

New PromptError class for symmetry with ToolError and ResourceError.

Security improvement (#698): Unexpected exceptions no longer leak internal details (e.g., database connection strings, file paths) to the client. Only user-raised ToolError/ResourceError/PromptError messages reach the client.

User-facing behavior

@server.tool()
def my_tool(x: int) -> str:
    raise ToolError("x must be positive")     # → CallToolResult(is_error=True, text="x must be positive")
    raise MCPError(code=..., message="...")    # → JSON-RPC error response
    raise RuntimeError("secret db password")  # → sanitized: "Error executing tool my_tool"

@server.resource("resource://data")
def my_resource() -> str:
    raise ResourceError("access denied")      # → MCPError(INVALID_PARAMS, "access denied")

@server.prompt()
def my_prompt(name: str) -> str:
    raise PromptError("invalid context")      # → MCPError(INVALID_PARAMS, "invalid context")

Test plan

• 9 new tests covering all error paths (tool/resource/prompt × user-raised/unexpected/MCPError)
• Updated existing tests to match sanitized error messages
• All 315 existing mcpserver tests pass
• Verified ToolError, ResourceError, PromptError messages reach client correctly
• Verified unexpected exceptions do NOT leak internal details

🤖 Generated with Claude Code