v0.4.0 - Errors, MCP utilities and new StreamabeHTTP

[patvice]

Release v0.4.0: Enhanced Error Handling, Utilities, and StreamableHTTP Transport Improvements

This release brings significant improvements to error handling, introduces new utility features, and includes a complete rewrite of the streamable HTTP transport with migration from Faraday to HTTPX, and prep for client side responses.

✨ New Features

Notification Support

• MCP Notification communication with MCP servers. All defined notifications in the MPC spec are are now supported
• Resource Subscriptions support marking resources dirty and refetching content when MPC pass a resource updated notification
• Support list change notifications tools, resources and prompts list will be refetched when MCP send a notification that they have changed
• Message Notification logging events can down be feed from the server to the client to give debug or general information
• Progress Notification progress notification and progress hooks are now available to update on progress on tool execution timing

Enhanced Error Handling & Utilities

• Improved logging capabilities with configurable log levels support server fed logs
• Progress tracking utilities for long-running operations, allowing for MCPs to update progress
• Human-in-the-loop support with callback mechanisms for tool execution approval, allowing for some user feedback or programmatic controller over what tools & parameters can be called
• • Comprehensive error management system with detailed error types and context, using all standard error types defined in the MPC spec
• Ping is now supported bidirectionally, allowing for pinging server and clinic responding to pings.

Streamable HTTP Transport Rewrite

• Complete rewrite of the StreamableHTTP transport class
• Enhanced SSE (Server-Sent Events) support with:
  • Automatic reconnection with exponential backoff
  • Better error handling and recovery
  • Improved connection lifecycle management
  • Thread-safe operations with proper cleanup
• Bidirectional streaming capabilities for real-time communication, starting with ping support as the first bidirectional action
• Session management with proper termination handling, including deletion on close

🔧 Breaking Changes

HTTP Client Migration: Faraday → HTTPX

• Migrated from Faraday to HTTPX for all HTTP transport operations
• Reason: While Faraday is used by RubyLLM, it has critical issues with reading text/event-stream responses, which are essential for MCP's Streamable and Server-Sent Events (SSE) transports. Faraday (while works great in RubyLLM) has some issues with reason text/event_streams from post method requests.
• HTTPX provides better streaming support and more reliable handling of SSE connections and modern http handing behaviours

Error Handling

• Improved error handing returns cleaning up what errors can be send from all transports and standardized behaviours. New errors (in a more structured format) will now fire on transport errors.

Reduced Client surface area

• Reduced public surface area for cleaner API design. Cliented used to include methods that were ment for internal use only as public methods to allow downstream classes to access transport.
• New Coordinator class an internal class that will manage transport and server interactions
• Centralized request/response handling across all transport types

🛠️ Improvements

Transport Layer Enhancements

• Improved SSE connection stability with better error handling
• Enhanced timeout management across all transport types
• Better connection pooling and resource cleanup
• Thread-safe operations with proper synchronization

Testing & Reliability

• Comprehensive test coverage for all transport types (SSE, stdio, streamable)
• Cross-provider testing with Anthropic Claude, OpenAI GPT-4, Gemini, and DeepSeek for prompts
• VCR cassette updates for consistent test replay
• Improved spec infrastructure with better test server management

🔍 Technical Details

New Classes & Modules

• RubyLLM::MCP::Coordinator - Central coordination of transport operations
• RubyLLM::MCP::Error & RubyLLM::MCP::Errors - Comprehensive error handling
• RubyLLM::MCP::Logging - Enhanced logging capabilities
• RubyLLM::MCP::Progress - Progress tracking utilities
• Multiple new request types for expanded MCP protocol support

Enhanced Transport Classes

• StreamableHTTP: Complete rewrite with HTTPX integration
• SSE: Improved reliability and error handling
• Stdio: Enhanced process management and communication

Protocol Support Expansion

• Notification handling for server-initiated communications
• Ping/pong mechanisms for connection health checks
• Logging level management for debugging
• Cancellation support for long-running operations (now fires when clinic triggers a timeout)

🧪 Testing

• 95+ new test cases covering error scenarios, edge cases, and transport reliability
• Cross-transport testing ensuring consistency across SSE, stdio, and streamable transports
• Provider compatibility testing with major LLM providers
• Stress testing for connection management and recovery

📚 Documentation

• Updated README with comprehensive examples
• Enhanced API documentation
• New error handling guides
• Transport selection guidelines

🔄 Migration Guide

For users upgrading from v0.3.x:

1. No breaking API changes for standard usage
2. Error handling may surface different exception types (more specific)
3. Logging output format has been enhanced
4. Transport configuration remains the same