GitHub Issue #2: Add Input Format Tolerance for Better MCP Client Compatibility

Issue Type

✨ Feature Request

Summary

The SDK currently only accepts parsed objects for the __evmauth parameter, but some MCP clients send authentication data as JSON strings. Adding input format tolerance would improve out-of-the-box compatibility with various MCP client implementations.

Current Behavior

The SDK expects __evmauth to always be a parsed JavaScript object:

// Expected format
{
  __evmauth: {
    challenge: { /* object */ },
    signature: "0x..."
  }
}

However, some MCP clients send the authentication as a JSON string:

// Actual format from some clients
{
  __evmauth: "{\"challenge\":{...},\"signature\":\"0x...\"}"
}

This causes authentication failures even when the underlying proof data is valid.

Motivation

Different MCP client implementations handle JSON serialization differently:

• Node.js MCP clients: Often send parsed objects
• Web-based clients: May send JSON strings due to serialization layers
• Claude Web: Sends JSON strings that require parsing
• Proxy servers: May double-serialize authentication data

Proposed Solution

Add graceful handling for both input formats in the authentication extraction logic. The SDK already has this logic implemented (lines ~638-643) but it could be enhanced.

Current Implementation

File: src/radius-mcp-sdk.ts
Lines: ~638-643

if (typeof auth === 'string') {
  try {
    auth = JSON.parse(auth);
    if (this.config.debug) {
      console.log('[Radius] Parsed stringified proof', {
        step: 'proof_extraction',
        // ...
      });
    }
  } catch (error) {
    // Error handling needed here
  }
}

Enhancement Needed

1. Better Error Handling: Clear error messages for invalid JSON
2. Validation: Ensure parsed object has required structure
3. Logging: Improved debug information about format conversion
4. Testing: Unit tests for both input formats

Benefits

• Wider Compatibility: Works with more MCP client implementations
• Better Developer Experience: No need for client-side format adjustments
• Reduced Integration Time: Developers don't need to debug format issues
• Future-Proof: Handles various serialization approaches

Implementation Details

Expected Behavior

The SDK should gracefully accept __evmauth parameter in both formats:

1. Object Format (already supported): Direct JavaScript objects
2. JSON String Format (needs improvement): Stringified JSON that gets parsed automatically
3. Clear Error Messages: When format is invalid, provide actionable error messages
4. Consistent Processing: Both formats should result in identical authentication behavior

Developer Experience Impact

Current Developer Experience

1. Client-Specific Failures: Some MCP clients work perfectly while others fail mysteriously
2. Serialization Debugging: Developers must debug whether their client sends objects or strings
3. Workaround Requirements: Developers may need to implement format conversion in their applications
4. Limited Documentation: Unclear what format is expected or supported

Expected Developer Experience

1. Universal Compatibility: SDK works with any MCP client regardless of serialization approach
2. No Format Concerns: Developers don't need to worry about object vs string formats
3. Clear Error Messages: When authentication data is truly invalid, error messages clearly indicate the problem
4. Seamless Integration: Faster integration with various MCP client implementations

Backward Compatibility

✅ Fully backward compatible - existing code using object format will continue working unchanged.

Documentation Updates

• Update README with examples of both input formats
• Add troubleshooting guide for authentication format issues
• Include client integration examples

Environment

• SDK Version: Latest
• Affected Clients: Claude Web, custom web-based MCP clients
• Node.js: 16.0.0+

Additional Context

This enhancement was identified during real-world integration testing with Claude Web, where the client's serialization layer converts authentication objects to JSON strings. The SDK's existing partial handling shows this was anticipated, but could be improved.

Acceptance Criteria

• Both JSON string and object formats accepted for __evmauth
• Clear error messages for invalid formats
• Comprehensive test coverage for all format scenarios
• Debug logging shows format conversion details
• Documentation updated with examples
• Backward compatibility maintained
• Performance impact is negligible

Labels: enhancement, compatibility, developer-experience
Priority: Medium
Milestone: Next Release