DollhouseMCP

# REPAIR-2 Report - Fix Implementation and Analysis **Date**: August 21, 2025 PM **Agent**: REPAIR-2 (Tool Pipeline Debug & Fix Implementation Specialist) **Mission**: Implement MCP SDK upgrade and validate tool execution pipeline fixes ## Executive Summary 🔍 **Critical Finding**: REPAIR-1's SDK version diagnosis was incomplete. The tool execution timeout issue is **NOT** resolved by SDK upgrade alone. ⚠️ **Current Status**: ZodError persists across all MCP SDK versions (1.16.0 → 1.17.3), indicating a deeper JSON-RPC message serialization issue. 🎯 **Revised Root Cause**: Server-side message deserialization failure during CallToolRequest processing, where `params` field is received as string instead of parsed JSON object. ## Implementation Results ### 🔧 SDK Upgrade Implementation 1. ✅ **Updated package.json**: `@modelcontextprotocol/sdk` from 1.16.0 → 1.17.3 2. ✅ **Rebuilt project**: TypeScript compilation successful 3. ✅ **Tested multiple versions**: 1.16.0, 1.17.0, 1.17.3 all exhibit same issue 4. ❌ **Issue persists**: Tool execution still times out with identical ZodError ### 🔍 Diagnostic Results #### Tool Discovery vs Execution Performance ``` Tool Discovery: ✅ SUCCESS - 41 tools registered, <1ms response Server Connection: ✅ SUCCESS - ~40ms connection time Tool Execution: ❌ FAILURE - 100% timeout after 5 seconds ``` #### Error Pattern Analysis ``` ZodError: [ { "code": "invalid_union", "unionErrors": [{ "issues": [{ "code": "invalid_type", "expected": "object", "received": "string", "path": ["params"], "message": "Expected object, received string" }] }] } ] ``` **Key Insight**: The error occurs in `deserializeMessage()` in MCP SDK's stdio transport layer, suggesting the JSON-RPC message format is incorrect. ### 📊 Test Results Across SDK Versions | SDK Version | Connection | Tool Discovery | Tool Execution | Error Pattern | |------------|------------|----------------|----------------|---------------| | 1.16.0 | ✅ 40ms | ✅ <1ms (41 tools) | ❌ Timeout 5s | ZodError: params string vs object | | 1.17.0 | ✅ 41ms | ✅ <1ms (41 tools) | ❌ Timeout 5s | ZodError: params string vs object | | 1.17.3 | ✅ 39ms | ✅ <1ms (41 tools) | ❌ Timeout 5s | ZodError: params string vs object | **Conclusion**: SDK version is not the root cause. ### 🧪 Cross-Client Validation Tested with multiple client implementations: - ✅ **REPAIR-1's isolated test**: Same ZodError - ✅ **Existing QA scripts**: Same ZodError - ✅ **Main server test**: Same ZodError - ❌ **MCP Inspector**: Unable to complete test (tool execution timeout) ## Actions Taken ### 1. SDK Version Testing ```bash # Tested multiple SDK versions npm install @modelcontextprotocol/sdk@1.16.0 # Original npm install @modelcontextprotocol/sdk@1.17.0 # First 1.17.x npm install @modelcontextprotocol/sdk@1.17.3 # Latest stable ``` ### 2. Minimal Test Case Validation ```bash node test-minimal-isolated-client.js node debug-tool-timeout.js node scripts/qa-simple-test.js ``` All exhibit identical ZodError pattern. ### 3. Server Architecture Analysis - ✅ CallToolRequest handler correctly extracts `request.params.name` and `request.params.arguments` - ✅ Tool registry properly registers 41 tools - ✅ StdioServerTransport setup follows SDK best practices - ❌ Message deserialization fails before reaching tool handlers ## 💡 Revised Root Cause Analysis ### Primary Issue: JSON-RPC Message Format Problem The error indicates that when a client sends a CallToolRequest, the MCP SDK's `deserializeMessage()` function cannot parse the message properly. Specifically: 1. **Expected**: `params` as JSON object `{"name": "tool_name", "arguments": {...}}` 2. **Received**: `params` as string value (possibly stringified JSON) 3. **Impact**: Message never reaches tool handlers → timeout ### Secondary Issues Eliminated - ❌ MCP SDK version compatibility (tested across versions) - ❌ Tool registration problems (discovery works perfectly) - ❌ Server initialization issues (connection succeeds) - ❌ Application logic blocking (minimal test cases timeout) ### Potential Root Causes 1. **Message Serialization**: Client sending incorrect JSON-RPC format 2. **Transport Layer**: StdioTransport configuration issue 3. **Node.js/ES Module**: Import/export compatibility problem 4. **Environmental**: npm/dependency version conflicts ## Recommendations for REPAIR-3 ### 🎯 Investigation Priorities 1. **Message Format Debugging**: - Add debug logging to MCP SDK transport layer - Capture raw stdio messages between client/server - Verify JSON-RPC message structure 2. **Transport Layer Analysis**: - Compare working vs non-working server configurations - Test with alternative transport methods - Verify stdio handling in current environment 3. **Dependency Audit**: - Check for version conflicts in transitive dependencies - Verify Zod schema versions used by MCP SDK - Test with clean npm install environment ### 🔍 Debug Focus Areas ```javascript // Add debug logging to capture raw messages server.onerror = (error) => { console.error("Server error with raw message details:", error); }; // Test message format manually const testMessage = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "get_user_identity", arguments: {} } }; ``` ### 🛠️ Alternative Fix Strategies #### Strategy 1: Message Format Fix - Investigate if client is double-encoding JSON - Check for `JSON.stringify()` issues in message serialization - Verify MCP protocol version compatibility #### Strategy 2: Transport Layer Replacement - Test with alternative transport mechanisms - Consider HTTP transport vs stdio transport - Validate with known-working MCP implementations #### Strategy 3: Environmental Reset - Clean npm install with locked versions - Test in isolated Docker environment - Compare against working server deployment ## Technical Details ### Current SDK Configuration ```json { "dependencies": { "@modelcontextprotocol/sdk": "^1.17.3" } } ``` ### Error Location ``` File: node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js:26 Function: deserializeMessage() Issue: Zod schema validation failure on params field ``` ### Success Criteria for Fix - [ ] Tool execution success rate: 0% → >95% - [ ] Response time: Timeout → <3 seconds - [ ] All 42 registered tools functional - [ ] QA automation scripts operational - [ ] No regression in server startup or tool discovery ## Risk Assessment ### High Risk - **Deep Protocol Issue**: May require significant changes to message handling - **SDK Incompatibility**: Possible incompatibility with current MCP protocol version - **Environmental Dependency**: Issue may be environment-specific ### Mitigation Strategies - Focus on message format debugging before major changes - Test incremental fixes to avoid breaking working components - Maintain capability to rollback to known working state - Document all changes for future debugging ## Conclusion The tool execution timeout is definitively **NOT** caused by MCP SDK version issues. The problem lies deeper in the JSON-RPC message serialization/deserialization process. The MCP SDK is receiving malformed messages where the `params` field is a string instead of a parsed JSON object. **Confidence Level**: 90% - Systematic testing across versions confirms SDK is not root cause **Fix Complexity**: Medium-High - Requires message format debugging and protocol analysis **Urgency**: Critical - Blocks all QA automation and MCP functionality --- **Next Agent**: REPAIR-3 should focus on message format debugging and JSON-RPC protocol analysis rather than code changes. The issue is in the communication layer, not the application logic.