Feat/turbomcp

[nicholasjpaterno]

Add TurboMCP Support to Rig: Alternative MCP Implementation with Advanced Features

Summary

This PR adds TurboMCP as an alternative MCP implementation option in Rig, providing users with a choice between two high-quality MCP libraries. TurboMCP offers additional features like OAuth 2.1 compliance, enterprise plugins, and enhanced content type support while maintaining identical APIs to the existing RMCP integration.

Changes Made to Rig

New Feature Flag: turbomcp

Users can now choose their preferred MCP implementation:

# Existing default - unchanged
rig = { version = "0.19", features = ["rmcp"] }

# New option - TurboMCP
rig = { version = "0.19", features = ["turbomcp"] }

# For testing/migration
rig = { version = "0.19", features = ["all-mcp"] }

Code Changes

1. rig-core/Cargo.toml

• Added TurboMCP dependencies as optional features
• Uses published crates (v1.0.8) from crates.io
• Properly feature-gated to avoid bloating default installations

2. rig-core/src/tool.rs

• Added new turbomcp module alongside existing rmcp module
• Implemented TurboMcpTool struct with identical interface to McpTool
• Maintains feature parity while supporting additional content types
• Zero impact on existing RMCP code

3. rig-core/src/agent/builder.rs

• Added turbomcp_tool() method with identical signature to rmcp_tool()
• Both methods follow the same patterns and conventions
• Consistent builder API regardless of MCP implementation choice

4. Examples Added

• mcp_demo.rs: Shows both RMCP and TurboMCP side-by-side
• turbomcp_simple_demo.rs: Basic TurboMCP integration
• turbomcp_plugin_demo.rs: Demonstrates advanced plugin features

API Compatibility

The integration maintains perfect API compatibility:

// RMCP (existing) - unchanged
agent.rmcp_tool(tool, client);

// TurboMCP (new) - identical pattern
agent.turbomcp_tool(tool, client);

Both methods:

• Take the same parameter types (tool definition + client)
• Return the same builder pattern
• Integrate with Rig's agent system identically
• Handle errors consistently

Feature Comparison in Rig

Capability	RMCP in Rig	TurboMCP in Rig	Notes
Text Content	✅	✅	Identical support
Image Content	✅	✅	Identical support
Resource Content	✅	✅	Identical support
Audio Content	❌	✅	TurboMCP adds this capability
Error Handling	✅	✅	Consistent patterns
Agent Builder	✅	✅	Same API design
Plugin Middleware	❌	✅	Optional enterprise features
OAuth 2.1	❌	✅	Optional authentication

Implementation Benefits for Rig Users

Choice and Flexibility

• Users can select the MCP implementation that best fits their needs
• No lock-in to a single MCP library
• Easy migration path between implementations

Enhanced Capabilities (Optional)

• Audio content support for multimedia applications
• Enterprise plugin system for production deployments
• OAuth 2.1 compliance for secure integrations
• Multiple transport protocols beyond HTTP

Risk Mitigation

• Reduces dependency on single MCP implementation
• Provides fallback option if one library has issues
• Healthy competition drives improvements in both libraries

Backward Compatibility

Zero breaking changes:

• All existing RMCP code continues to work unchanged
• Default behavior remains identical
• No impact on users who don't opt into TurboMCP
• All existing tests pass without modification

Testing Strategy

Compilation Testing

✅ cargo check --features rmcp          # Existing functionality
✅ cargo check --features turbomcp      # New functionality
✅ cargo check --features all-mcp       # Both together

Feature Isolation

• TurboMCP code only compiles when turbomcp feature is enabled
• No performance or binary size impact on RMCP users
• Clean separation of dependencies

Code Quality Standards

Consistency with Rig Patterns

• Follows existing Rig module organization
• Uses same error handling patterns as RMCP integration
• Maintains consistent code style and documentation
• Proper feature gating throughout

Documentation

• Clear examples showing integration with Rig
• Feature comparison focused on user benefits
• Migration guide for users wanting to switch

Why This Approach?

User-Centric Design

Instead of forcing users to one MCP implementation, Rig now:

• Provides choice based on specific needs
• Maintains stability for existing users
• Enables access to advanced features when needed

Engineering Best Practices

• Clean abstraction over multiple implementations
• Consistent APIs regardless of underlying library
• Proper dependency management with feature flags
• Zero technical debt introduced

Future Considerations

Monitoring Adoption

• Track which implementation gains more usage
• Gather user feedback on feature preferences
• Consider deprecation path if one becomes dominant

API Evolution

• Ensure new features work consistently across both implementations
• Maintain compatibility guidelines
• Plan for potential API extensions

Breaking Changes

None. This is a purely additive change:

• Default behavior unchanged
• All existing APIs preserved
• New functionality opt-in only

Files Changed

Core Integration

• rig-core/Cargo.toml - Added TurboMCP dependencies
• rig-core/src/tool.rs - Added TurboMCP module
• rig-core/src/agent/builder.rs - Added turbomcp_tool() method

Examples

• rig-core/examples/mcp_demo.rs - Enhanced to show both implementations
• rig-core/examples/turbomcp_simple_demo.rs - New basic demo
• rig-core/examples/turbomcp_plugin_demo.rs - New advanced demo

Checklist

• TurboMCP integration follows Rig patterns exactly
• API consistency maintained between RMCP and TurboMCP
• Feature flags properly isolate functionality
• All existing tests pass unchanged
• New examples demonstrate Rig integration (not library features)
• Documentation focuses on user benefits within Rig
• Zero breaking changes confirmed
• Uses published crates (not development dependencies)

[nicholasjpaterno]

Resolves #750

[joshua-mo-143]

Some minor queries on the implementation design, primarily around the use of Arc/implementing the turbo MCP client for a Mutex.

Other than that, you basically just need to make the CI pass and that's it.

[nicholasjpaterno]

Really appreciate the feedback @joshua-mo-143! The TurboMCP client has had the least attention of all the crates in the library. We've just implemented a comprehensive solution to address this exact concern and I'm shipping this now.

SharedClient Pattern: Instead of requiring users to manually wrap clients in Arc<Mutex<>>

  // Before (what you saw in the PR):
  let client = Arc::new(Mutex::new(turbomcp_client::Client::new(transport)));

  // After (clean API):
  let client = SharedClient::new(turbomcp_client::Client::new(transport));
  let client_clone = client.clone(); // Easy sharing across tasks

We've implemented this pattern for all major components:

• SharedClient - for client instances
• SharedServer - for server instances
• SharedTransport - for transport layer
• SharedElicitationCoordinator - for elicitation management
• Generic Shared and ConsumableShared - for any custom types

Key benefits for Rig integration:

1. No more Arc/Mutex exposure: Clean, ergonomic APIs that hide synchronization complexity
2. Clone-able: All shared wrappers implement Clone for easy task sharing
3. Drop-in replacement: Zero changes needed to existing Rig code
4. Thread-safe by design: All wrappers handle concurrent access correctly

For this specific case:

  // Instead of Arc<dyn TurboMcpClient>, you can now use:
  pub struct TurboMcpTool<C = SharedClient<StdioTransport>> {
      definition: turbomcp_protocol::types::Tool,
      client: C, // Generic over client type, defaults to SharedClient
  }

  // Or keep it simple with the shared wrapper:
  pub struct TurboMcpTool {
      definition: turbomcp_protocol::types::Tool,
      client: SharedClient<impl Transport>, // Clean, clone-able, thread-safe
  }

This addresses both the Arc concern (no more exposed Arc types) and the generic request (you can make it generic over the client type while still having a sensible default).

The design maintains strict MCP protocol compliance while providing the ergonomic async-friendly APIs that Rig needs.

[joshua-mo-143]

Needs CI to pass then we can merge this in

[nicholasjpaterno]

Sounds great! Clippy and fmt look good and all tests pass locally. I just need to kick off another CI pass.

[joshua-mo-143]

Looks like one more round of CI (you might need to use cargo test --all-features --all-targets if you aren't already)

[nicholasjpaterno]

Seems like the rmcp dep bumped to 0.6.4 which adds these properties to the client info:

           icons: None,
           title: None,
           website_url: None,

[nicholasjpaterno]

Appreciate your patience on this! We had a big release up coming so I paused the integration until we shipped! In any case, I rebased so it should be a clean FF, though I suspect you'll want to squash this for a nice clean commit history.

[nicholasjpaterno]

Comparing the ergonomics, I hope this enables your users to ship mcp support without all the boilerplate!

[joshua-mo-143]

This macro is not required because of requiring the example already have the turbomcp feature

[joshua-mo-143]

one very final small change (edit: and a CI pass) then this can get merged

[nicholasjpaterno]

We are shipping 2.0 very soon, really appreciate your patience on this! The api has significantly improved and ossified.