feat: add Claude Code compatibility workaround for MCP specification violation

Add XCODEBUILDMCP_CLAUDE_CODE_WORKAROUND environment variable to consolidate
multiple content blocks into single text responses. This works around Claude Code''s
MCP spec violation where it only shows the first content block, preventing users
from seeing test results when stderr warnings are present.

Changes:
- Add consolidateContentForClaudeCode() utility function in validation.ts
- Update build-utils.ts and test-common.ts to apply consolidation
- Document new env var in CLAUDE.md
- Preserve correct MCP format by default, consolidate only when enabled

Fixes issue where test_sim_id_proj returns stderr warnings as errors,
preventing access to test results in Claude Code.

Co-authored-by: Cameron Cooke <cameroncooke@users.noreply.github.com>

Author: claude[bot]

CLAUDE.md

@@ -52,6 +52,11 @@ XcodeBuildMCP has two modes to manage its extensive toolset, controlled by the `
 - **Environment**: `XCODEBUILDMCP_DYNAMIC_TOOLS=true`.
 - **Behavior**: Only the `discover_tools` tool is available initially. You can use this tool by providing a natural language task description. The server then uses an LLM call (via MCP Sampling) to identify the most relevant workflow group and dynamically loads only those tools. This conserves context window space.
 
+#### Claude Code Compatibility Workaround
+- **Environment**: `XCODEBUILDMCP_CLAUDE_CODE_WORKAROUND=true`.
+- **Purpose**: Workaround for Claude Code's MCP specification violation where it only displays the first content block in tool responses.
+- **Behavior**: When enabled, multiple content blocks are consolidated into a single text response, separated by `---` dividers. This ensures all information (including test results and stderr warnings) is visible to Claude Code users.
+
 ### Core Architecture Layers
 1. **MCP Transport**: stdio protocol communication
 2. **Plugin Discovery**: Automatic tool AND resource registration system  

src/utils/build-utils.ts

@@ -21,7 +21,7 @@ import { log } from './logger.js';
 import { XcodePlatform, constructDestinationString } from './xcode.js';
 import { CommandExecutor } from './command.js';
 import { ToolResponse, SharedBuildParams, PlatformBuildOptions } from '../types/common.js';
-import { createTextResponse } from './validation.js';
+import { createTextResponse, consolidateContentForClaudeCode } from './validation.js';
 import {
   isXcodemakeEnabled,
   isXcodemakeAvailable,
@@ -273,7 +273,7 @@ export async function executeXcodeBuildCommand(
         });
       }
 
-      return errorResponse;
+      return consolidateContentForClaudeCode(errorResponse);
     }
 
     log('info', `✅ ${platformOptions.logPrefix} ${buildAction} succeeded.`);
@@ -347,13 +347,15 @@ When done capturing logs, use: stop_and_get_simulator_log({ logSessionId: 'SESSI
       });
     }
 
-    return successResponse;
+    return consolidateContentForClaudeCode(successResponse);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     log('error', `Error during ${platformOptions.logPrefix} ${buildAction}: ${errorMessage}`);
-    return createTextResponse(
-      `Error during ${platformOptions.logPrefix} ${buildAction}: ${errorMessage}`,
-      true,
+    return consolidateContentForClaudeCode(
+      createTextResponse(
+        `Error during ${platformOptions.logPrefix} ${buildAction}: ${errorMessage}`,
+        true,
+      ),
     );
   }
 }

src/utils/test-common.ts

@@ -20,7 +20,7 @@ import { join } from 'path';
 import { log } from './logger.js';
 import { XcodePlatform } from './xcode.js';
 import { executeXcodeBuildCommand } from './build-utils.js';
-import { createTextResponse } from './validation.js';
+import { createTextResponse, consolidateContentForClaudeCode } from './validation.js';
 import { ToolResponse } from '../types/common.js';
 import { CommandExecutor } from './command.js';
 
@@ -214,7 +214,7 @@ export async function handleTestLogic(
       await rm(tempDir, { recursive: true, force: true });
 
       // Return combined result - preserve isError from testResult (test failures should be marked as errors)
-      return {
+      const combinedResponse: ToolResponse = {
         content: [
           ...(testResult.content || []),
           {
@@ -224,6 +224,9 @@ export async function handleTestLogic(
         ],
         isError: testResult.isError,
       };
+
+      // Apply Claude Code workaround if enabled
+      return consolidateContentForClaudeCode(combinedResponse);
     } catch (parseError) {
       // If parsing fails, return original test result
       log('warn', `Failed to parse xcresult bundle: ${parseError}`);
@@ -235,11 +238,13 @@ export async function handleTestLogic(
         log('warn', `Failed to clean up temporary directory: ${cleanupError}`);
       }
 
-      return testResult;
+      return consolidateContentForClaudeCode(testResult);
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     log('error', `Error during test run: ${errorMessage}`);
-    return createTextResponse(`Error during test run: ${errorMessage}`, true);
+    return consolidateContentForClaudeCode(
+      createTextResponse(`Error during test run: ${errorMessage}`, true),
+    );
   }
 }

src/utils/validation.ts

@@ -207,5 +207,49 @@ export function validateEnumParam<T>(
   return { isValid: true };
 }
 
+/**
+ * Consolidates multiple content blocks into a single text response for Claude Code compatibility
+ *
+ * Claude Code violates the MCP specification by only showing the first content block.
+ * This function provides a workaround by concatenating all text content into a single block.
+ *
+ * @param response The original ToolResponse with multiple content blocks
+ * @returns A new ToolResponse with consolidated content
+ */
+export function consolidateContentForClaudeCode(response: ToolResponse): ToolResponse {
+  // Check environment variable to enable/disable this workaround
+  const shouldConsolidate = process.env.XCODEBUILDMCP_CLAUDE_CODE_WORKAROUND === 'true';
+
+  if (!shouldConsolidate || !response.content || response.content.length <= 1) {
+    return response;
+  }
+
+  // Extract all text content and concatenate with separators
+  const textParts: string[] = [];
+
+  response.content.forEach((item, index) => {
+    if (item.type === 'text') {
+      // Add a separator between content blocks (except for the first one)
+      if (index > 0 && textParts.length > 0) {
+        textParts.push('\n---\n');
+      }
+      textParts.push(item.text);
+    }
+    // Note: Image content is not handled in this workaround as it requires special formatting
+  });
+
+  const consolidatedText = textParts.join('');
+
+  return {
+    ...response,
+    content: [
+      {
+        type: 'text',
+        text: consolidatedText,
+      },
+    ],
+  };
+}
+
 // Export the ToolResponse type for use in other files
 export { ToolResponse, ValidationResult };