josharsh / josharsh/claude-utils

MCP server incompatible with Claude Code - protocol version and JSON key format issues

Open
#3 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
6
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Description

The MCP server implementation is currently **incompatible with Claude Code** due to two protocol issues that prevent successful connection.

## Environment

- Claude Code version: Latest
- claude-utils version: 0.1.1
- OS: Tested on Windows and Linux (WSL)

## Problems Identified

### 1. Protocol Version Format (Critical)

**Current behavior:**
```json
{
"protocolVersion": "1.0"
}
```

**Expected behavior (per MCP spec):**
```json
{
"protocolVersion": "2024-11-05"
}
```

The MCP specification uses date-based version strings, not semantic versioning. Claude Code rejects connections with unrecognized protocol versions.

**Location:** `src/mcp/server.rs:173`

### 2. JSON Key Format (Critical)

**Current behavior:** Keys are serialized in `snake_case`
```json
{
"protocol_version": "1.0",
"server_info": { ... }
}
```

**Expected behavior (per MCP spec):** Keys should be in `camelCase`
```json
{
"protocolVersion": "2024-11-05",
"serverInfo": { ... }
}
```

**Location:** `src/mcp/protocol.rs` - Missing `#[serde(rename_all = "camelCase")]` attributes

## Test Results

| Configuration | Result |
|--------------|--------|
| Original (version "1.0" + snake_case) | ❌ Failed to connect |
| Version "2024-11-05" only | ❌ Failed to connect |
| camelCase only | ❌ Failed to connect |
| **Version "2024-11-05" + camelCase** | ✅ **Connected** |

Both fixes are required - neither works alone.

## Proposed Fix

1. Change protocol version in `server.rs`:
```rust
protocol_version: "2024-11-05".to_string(),
```

2. Add serde rename attributes in `protocol.rs`:
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct InitializeResponse { ... }

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Tool { ... }
```

## References

- [MCP Specification - Lifecycle](https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle)
- [Claude Code MCP Documentation](https://code.claude.com/docs/mcp)

## Additional Notes

The clipboard functionality works perfectly once connected. This is purely a protocol handshake issue.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.