Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
183 lines (136 loc) · 4.53 KB

MIGRATION_GUIDE.md

File metadata and controls

183 lines (136 loc) · 4.53 KB

Migration Guide: Fixing Claude Code Compatibility

⚠️ Critical Compatibility Issue (Resolved in v1.4.0+)

If your MCP server cannot connect to Claude Code, you are likely using an older version of pmcp that has a JSON-RPC compatibility issue.

The Problem

Versions of pmcp prior to v1.4.0 used a custom message format that was incompatible with Claude Code and other standard MCP clients.

What Claude Code expects (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": { ... }
}

What old pmcp versions expected:

{
  "id": 1,
  "request": {
    "Client": {
      "Initialize": { ... }
    }
  }
}

This caused:

  • Connection timeouts with Claude Code
  • "Invalid JSON" errors
  • Complete inability to use Rust-based MCP servers

The Solution

Upgrade to pmcp v1.4.1 or later, which includes full JSON-RPC 2.0 compatibility.

Migration Steps

1. Update your Cargo.toml

[dependencies]
pmcp = "1.4.1"  # or latest version

2. Remove any compatibility workarounds

If you have custom JSON-RPC conversion code, remove it. The SDK now handles this automatically.

Before (workaround code):

// Custom JSON-RPC to TransportMessage conversion
fn convert_jsonrpc_to_transport(json: Value) -> TransportMessage {
    // Complex conversion logic
}

After (just use the SDK):

// No conversion needed - SDK handles it internally
server.run_stdio().await?;

3. Update and rebuild

cargo update
cargo clean
cargo build --release

4. Test with Claude Code

# Add your server to Claude Code
claude mcp add my-server ./target/release/my-mcp-server

# Test the connection
claude mcp test my-server

Common Issues and Solutions

Issue: "data did not match any variant of untagged enum TransportMessage"

Cause: Using pmcp < 1.4.0 with Claude Code
Solution: Upgrade to pmcp 1.4.1+

Issue: Connection timeout after 30 seconds

Cause: Server cannot parse JSON-RPC messages from Claude Code
Solution: Upgrade to pmcp 1.4.1+

Issue: Server works with custom client but not Claude Code

Cause: Custom client using old pmcp message format
Solution: Upgrade both server and client to pmcp 1.4.1+

Version Compatibility Matrix

pmcp Version Claude Code TypeScript SDK Python SDK Notes
< 1.4.0 ❌ ❌ ❌ Custom format only
1.4.0 ✅ ✅ ✅ JSON-RPC 2.0 added
1.4.1+ ✅ ✅ ✅ Recommended

Example: Minimal Claude Code Compatible Server

use pmcp::{Server, ServerCapabilities, ToolHandler};
use async_trait::async_trait;

struct MyTool;

#[async_trait]
impl ToolHandler for MyTool {
    async fn handle(
        &self, 
        args: serde_json::Value, 
        _extra: pmcp::RequestHandlerExtra
    ) -> Result<serde_json::Value, pmcp::Error> {
        Ok(serde_json::json!({
            "result": "Tool executed successfully"
        }))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Server::builder()
        .name("my-mcp-server")
        .version("1.0.0")
        .capabilities(ServerCapabilities::tools_only())
        .tool("my_tool", MyTool)
        .build()?;

    // This now works with Claude Code!
    server.run_stdio().await?;
    Ok(())
}

Testing Your Migration

  1. Create a test script (test_connection.sh):
#!/bin/bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
    timeout 5 ./target/release/my-mcp-server
  1. Expected output (successful connection):
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}}}

For Library Authors

If you maintain a library that depends on pmcp:

  1. Update your dependency to require pmcp 1.4.1+:
[dependencies]
pmcp = "^1.4.1"
  1. Add a note in your README about Claude Code compatibility
  2. Consider adding a compatibility test

Need Help?

Remember: The compatibility issue is completely resolved in pmcp 1.4.1+. A simple version upgrade is all you need!