Add diagnostic tool

Author: cameroncooke

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -16,24 +16,22 @@ body:
       placeholder: When trying to build my iOS app using the AI assistant...
     validations:
       required: true
-      
-  - type: input
-    id: macos-version
-    attributes:
-      label: macOS Version
-      description: The version of macOS you're using
-      placeholder: macOS 15.4.1
-    validations:
-      required: true
-      
-  - type: input
-    id: xcode-version
+
+  - type: textarea
+    id: debug
     attributes:
-      label: Xcode Version
-      description: The version of Xcode you're using
-      placeholder: Xcode 16.3
+      label: Debug Output
+      description: Output from the diagnostic tool
+      placeholder: |
+        ```
+        # Run the diagnostic tool using mise
+        mise x npm:xcodebuildmcp@latest -- xcodebuildmcp-diagnostic
+        
+        # Or using npx
+        npx xcodebuildmcp@latest xcodebuildmcp-diagnostic
+        ```
     validations:
-      required: true
+      required: true      
 
   - type: input
     id: editor-client

CONTRIBUTING.md

@@ -64,10 +64,31 @@ To configure your MCP client to use your local XcodeBuildMCP server you can use
 
 You can use MCP Inspector via:
 
+```bash
+npm run inspect
+```
+
+or if you prefer the explict command:
+
 ```bash
 npx @modelcontextprotocol/inspector node build/index.js
 ```
 
+#### Using the diagnostic tool
+
+Running the XcodeBuildMCP server with the environmental variable `XCODEBUILDMCP_DEBUG=true` will expose a new diagnostic tool which you can run using MCP Inspector:
+
+
+```bash
+XCODEBUILDMCP_DEBUG=true npm run inspect
+```
+
+Alternatively, you can run the diagnostic tool directly:
+
+```bash
+node build/diagnostic-cli.js
+```
+
 ## Making changes
 
 1. Fork the repository and create a new branch

README.md

@@ -4,7 +4,6 @@ A Model Context Protocol (MCP) server that provides Xcode-related tools for inte
 
 ## Table of contents
 
-- [Table of contents](#table-of-contents)
 - [Overview](#overview)
 - [Why?](#why)
 - [Features](#features)
@@ -16,13 +15,17 @@ A Model Context Protocol (MCP) server that provides Xcode-related tools for inte
    * [One-line setup with mise](#one-line-setup-with-mise)
    * [Configure MCP clients](#configure-mcp-clients)
    * [Enabling UI Automation (beta)](#enabling-ui-automation-beta)
+- [Troubleshooting](#troubleshooting)
+   * [Diagnostic Tool](#diagnostic-tool)
+      + [Using with mise](#using-with-mise)
+      + [Using with npx](#using-with-npx)
 - [Demos](#demos)
    * [Autonomously fixing build errors in Cursor](#autonomously-fixing-build-errors-in-cursor)
+   * [Utilising the new UI automation and screen capture features](#utilising-the-new-ui-automation-and-screen-capture-features)
    * [Building and running iOS app in Claude Code](#building-and-running-ios-app-in-claude-code)
 - [Contributing](#contributing)
 - [Licence](#licence)
 
-
 ## Overview
 
 This project implements an MCP server that exposes Xcode operations as tools that can be invoked by AI agents via the MCP protocol. It enables programmatic interaction with Xcode projects through a standardised interface, optimised for agent-driven development workflows.
@@ -121,6 +124,38 @@ brew install idb-companion
 > [!NOTE]
 > Displaying images in tool responses and embedding them in chat context may not be supported by all MCP Clients; it's currently known to be supported in Cursor.
 
+## Troubleshooting
+
+If you encounter issues with XcodeBuildMCP, the diagnostic tool can help identify the problem by providing detailed information about your environment and dependencies.
+
+### Diagnostic Tool
+
+The diagnostic tool is a standalone utility that checks your system configuration and reports on the status of all dependencies required by XcodeBuildMCP. It's particularly useful when reporting issues.
+
+#### Using with mise
+
+```bash
+# Run the diagnostic tool using mise
+mise x npm:xcodebuildmcp@latest -- xcodebuildmcp-diagnostic
+```
+
+#### Using with npx
+
+```bash
+# Run the diagnostic tool using npx
+npx xcodebuildmcp@latest xcodebuildmcp-diagnostic
+```
+
+The diagnostic tool will output comprehensive information about:
+
+- System and Node.js environment
+- Xcode installation and configuration
+- Required dependencies (xcodebuild, idb, etc.)
+- Environment variables affecting XcodeBuildMCP
+- Feature availability status
+
+When reporting issues on GitHub, please include the full output from the diagnostic tool to help with troubleshooting.
+
 ## Demos
 
 ### Autonomously fixing build errors in Cursor

example_projects/macOS/MCPTest.xcodeproj/xcshareddata/xcschemes/MCPTestTests.xcscheme

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1630"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO"
+            parallelizable = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "8BA9F8302D62A18100C22D5D"
+               BuildableName = "MCPTestTests.xctest"
+               BlueprintName = "MCPTestTests"
+               ReferencedContainer = "container:MCPTest.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

package.json

@@ -4,15 +4,18 @@
   "main": "build/index.js",
   "type": "module",
   "bin": {
-    "xcodebuildmcp": "./build/index.js"
+    "xcodebuildmcp": "./build/index.js",
+    "xcodebuildmcp-diagnostic": "./build/diagnostic-cli.js"
   },
   "scripts": {
     "prebuild": "echo \"export const version = '$npm_package_version';\" > src/version.ts",
-    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755') && require('fs').chmodSync('build/diagnostic-cli.js', '755')\"",
     "lint": "eslint 'src/**/*.{js,ts}'",
     "lint:fix": "eslint 'src/**/*.{js,ts}' --fix",
     "format": "prettier --write 'src/**/*.{js,ts}'",
-    "format:check": "prettier --check 'src/**/*.{js,ts}'"
+    "format:check": "prettier --check 'src/**/*.{js,ts}'",
+    "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
+    "diagnostic": "node build/diagnostic-cli.js"
   },
   "files": [
     "build"

src/diagnostic-cli.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * XcodeBuildMCP Diagnostic CLI
+ *
+ * This standalone script runs the diagnostic tool and outputs the results
+ * to the console. It's designed to be run directly via npx or mise.
+ */
+
+import { version } from './version.js';
+
+// Set the debug environment variable
+process.env.XCODEBUILDMCP_DEBUG = 'true';
+
+async function runDiagnostic(): Promise<void> {
+  try {
+    // Using console.error to avoid linting issues as it's allowed by the project's linting rules
+    console.error(`Running XcodeBuildMCP Diagnostic Tool (v${version})...`);
+    console.error('Collecting system information and checking dependencies...\n');
+
+    const { runDiagnosticTool } = await import('./tools/diagnostic.js');
+
+    // Run the diagnostic tool
+    const result = await runDiagnosticTool({});
+
+    // Output the diagnostic information
+    if (result.content && result.content.length > 0) {
+      const textContent = result.content.find((item: { type: string }) => item.type === 'text');
+      if (textContent && 'text' in textContent) {
+        console.error(textContent.text);
+      } else {
+        console.error('Error: Unexpected diagnostic result format');
+      }
+    } else {
+      console.error('Error: No diagnostic information returned');
+    }
+
+    console.error('\nDiagnostic complete. Please include this output when reporting issues.');
+  } catch (error) {
+    console.error('Error running diagnostic:', error);
+    process.exit(1);
+  }
+}
+
+// Run the diagnostic
+runDiagnostic().catch((error) => {
+  console.error('Unhandled exception:', error);
+  process.exit(1);
+});

src/index.ts

@@ -82,6 +82,9 @@ import {
 // Import idb tools
 import { registerIdbTools } from './tools/idb.js';
 
+// Import diagnostic tool
+import { registerDiagnosticTool } from './tools/diagnostic.js';
+
 // Import idb setup utility
 import { setupIdb } from './utils/idb-setup.js';
 import { version } from './version.js';
@@ -153,6 +156,11 @@ async function main(): Promise<void> {
     setupIdb();
     registerIdbTools(server);
 
+    // Register diagnostic tool (only available when XCODEBUILDMCP_DEBUG is set)
+    if (process.env.XCODEBUILDMCP_DEBUG) {
+      registerDiagnosticTool(server);
+    }
+
     // Start the server
     await startServer(server);