Add iOS device deployment tools with JSON-based device discovery

Add complete physical device support with 5 new MCP tools for end-to-end iOS device workflows:

  • Device discovery and management via list_devices tool with JSON-based output
  • Native device building with build_ios_dev_proj/ws tools supporting incremental builds
  • App deployment via install_app_device and launch_app_device tools
  • Real-time console log capture with start/stop_device_log_cap session management
  • Physical device testing with test_ios_dev_proj/ws tools and detailed result parsing

  Key implementation details:
  - Standardized parameter naming (deviceId, bundleId, appPath) across all device tools
  - Added DEVICE_MANAGEMENT tool group for selective enablement parallel to simulator tools
  - Console output capture via xcrun devicectl with --terminate-existing flag for reliability
  - Proper error handling and session management for log capture workflows
  - Enhanced example iOS app with comprehensive startup and interaction logging

  Documentation and testing:
  - Updated README with device management features section and code signing prerequisites
  - Added code signing configuration guide for Xcode setup requirements
  - End-to-end tested complete device workflow: discover → build → install → launch → log capture → test
  - Verified console log capture works for both debugPrint and print statements

Author: cameroncooke

README.md

@@ -14,6 +14,7 @@ A Model Context Protocol (MCP) server that provides Xcode-related tools for inte
   - [Xcode project management](#xcode-project-management)
   - [Swift Package Manager](#swift-package-manager)
   - [Simulator management](#simulator-management)
+  - [Device management](#device-management)
   - [App utilities](#app-utilities)
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
@@ -24,6 +25,7 @@ A Model Context Protocol (MCP) server that provides Xcode-related tools for inte
     - [Alternative installation method using mise](#alternative-installation-method-using-mise)
     - [Installing via Smithery](#installing-via-smithery)
 - [Incremental build support](#incremental-build-support)
+- [Code Signing for Device Deployment](#code-signing-for-device-deployment)
 - [Troubleshooting](#troubleshooting)
   - [Diagnostic Tool](#diagnostic-tool)
     - [Using with npx](#using-with-npx)
@@ -75,15 +77,25 @@ The XcodeBuildMCP server provides the following tool capabilities:
 - **Clean Artifacts**: Remove build artifacts and derived data for fresh builds
 
 ### Simulator management
-- **Simulator Control**: List, boot, and open iOS simulators 
-- **App Deployment**: Install and launch apps on iOS simulators
+- **Simulator Control**: List, boot, and open simulators 
+- **App Deployment**: Install and launch apps on simulators
 - **Log Capture**: Capture run-time logs from a simulator
 - **UI Automation**: Interact with simulator UI elements (beta)
 - **Screenshot**: Capture screenshots from a simulator (beta)
 
+### Device management
+- **Device Discovery**: List connected physical Apple devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro)
+- **App Deployment**: Build, install, and launch apps on physical Apple devices across all platforms
+- **Testing**: Run test suites on physical devices with detailed results and cross-platform support
+- **Log Capture**: Capture console output from apps running on physical Apple devices
+- **Wireless Connectivity**: Connect to physical devices over Wi-Fi
+
 ### App utilities
-- **Bundle ID Extraction**: Extract bundle identifiers from iOS and macOS app bundles
-- **App Launching**: Launch built applications on both simulators and macOS
+- **Bundle ID Extraction**: Extract bundle identifiers from app bundles across all Apple platforms
+- **App Launching**: Launch built applications on simulators, physical devices, and macOS
+- 
+> [!IMPORTANT]
+> Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros. 
 
 ## Getting started
 
@@ -93,7 +105,7 @@ The XcodeBuildMCP server provides the following tool capabilities:
 - Xcode 16.x or later
 - Node 18.x or later
 - AXe 1.0.0 or later (optional, required for UI automation)
-  
+
 ### UI Automation
 
 For UI automation features (tap, swipe, type etc.), you'll need to install AXe:
@@ -132,6 +144,7 @@ Configure your MCP client (Windsurf, Cursor, Claude Desktop, Claude Code etc.) t
   }
 }
 ```
+
 #### Alternative installation method using mise
 
 Alternatively, you can use XcodeBuildMCP without a specific installation of Node.js by using `mise` to install it:
@@ -173,9 +186,6 @@ To install XcodeBuildMCP Server for Claude Desktop automatically via [Smithery](
 npx -y @smithery/cli install @cameroncooke/XcodeBuildMCP --client claude
 ```
 
-> [!IMPORTANT]
-> Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros. 
-
 ## Incremental build support
 
 XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`:
@@ -203,6 +213,18 @@ Example MCP client configuration:
 > [!IMPORTANT]
 > Please note that incremental builds support is currently highly experimental and your mileage may vary. Please report any issues you encounter to the [issue tracker](https://github.com/cameroncooke/XcodeBuildMCP/issues).
 
+## Code Signing for Device Deployment
+
+For device deployment features to work, code signing must be properly configured in Xcode **before** using XcodeBuildMCP device tools:
+
+1. Open your project in Xcode
+2. Select your project target
+3. Go to "Signing & Capabilities" tab
+4. Configure "Automatically manage signing" and select your development team
+5. Ensure a valid provisioning profile is selected
+
+> **Note**: XcodeBuildMCP cannot configure code signing automatically. This initial setup must be done once in Xcode, after which the MCP device tools can build, install, and test apps on physical devices.
+
 ## Troubleshooting
 
 If you encounter issues with XcodeBuildMCP, the diagnostic tool can help identify the problem by providing detailed information about your environment and dependencies.

example_projects/iOS_Calculator/CalculatorApp.xcodeproj/project.pbxproj

@@ -3,7 +3,7 @@
 	archiveVersion = 1;
 	classes = {
 	};
-	objectVersion = 56;
+	objectVersion = 71;
 	objects = {
 
 /* Begin PBXBuildFile section */
@@ -28,7 +28,7 @@
 /* End PBXFileReference section */
 
 /* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
-		8BD71C0A2DEE41E000CEDD92 /* Exceptions for "Config" folder in "CalculatorApp" target */ = {
+		8BD71C0A2DEE41E000CEDD92 /* PBXFileSystemSynchronizedBuildFileExceptionSet */ = {
 			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
 			membershipExceptions = (
 				Debug.xcconfig,
@@ -41,24 +41,9 @@
 /* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
 
 /* Begin PBXFileSystemSynchronizedRootGroup section */
-		8B41F6472DEDD0D5001A66F9 /* CalculatorApp */ = {
-			isa = PBXFileSystemSynchronizedRootGroup;
-			path = CalculatorApp;
-			sourceTree = "<group>";
-		};
-		8B9093512DF246C0008F026A /* CalculatorAppTests */ = {
-			isa = PBXFileSystemSynchronizedRootGroup;
-			path = CalculatorAppTests;
-			sourceTree = "<group>";
-		};
-		8BD71C052DEE41D800CEDD92 /* Config */ = {
-			isa = PBXFileSystemSynchronizedRootGroup;
-			exceptions = (
-				8BD71C0A2DEE41E000CEDD92 /* Exceptions for "Config" folder in "CalculatorApp" target */,
-			);
-			path = Config;
-			sourceTree = "<group>";
-		};
+		8B41F6472DEDD0D5001A66F9 /* CalculatorApp */ = {isa = PBXFileSystemSynchronizedRootGroup; explicitFileTypes = {}; explicitFolders = (); path = CalculatorApp; sourceTree = "<group>"; };
+		8B9093512DF246C0008F026A /* CalculatorAppTests */ = {isa = PBXFileSystemSynchronizedRootGroup; explicitFileTypes = {}; explicitFolders = (); path = CalculatorAppTests; sourceTree = "<group>"; };
+		8BD71C052DEE41D800CEDD92 /* Config */ = {isa = PBXFileSystemSynchronizedRootGroup; exceptions = (8BD71C0A2DEE41E000CEDD92 /* PBXFileSystemSynchronizedBuildFileExceptionSet */, ); explicitFileTypes = {}; explicitFolders = (); path = Config; sourceTree = "<group>"; };
 /* End PBXFileSystemSynchronizedRootGroup section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -180,6 +165,7 @@
 				};
 			};
 			buildConfigurationList = 8B41F6402DEDD0D5001A66F9 /* Build configuration list for PBXProject "CalculatorApp" */;
+			compatibilityVersion = "Xcode 14.0";
 			developmentRegion = en;
 			hasScannedForEncodings = 0;
 			knownRegions = (
@@ -188,7 +174,6 @@
 			);
 			mainGroup = 8B41F63C2DEDD0D5001A66F9;
 			minimizedProjectReferenceProxies = 1;
-			preferredProjectObjectVersion = 56;
 			productRefGroup = 8B41F6462DEDD0D5001A66F9 /* Products */;
 			projectDirPath = "";
 			projectRoot = "";
@@ -370,7 +355,9 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
+				DEVELOPMENT_TEAM = BR6WD3M6ZD;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_KEY_CFBundleDisplayName = "$(PRODUCT_DISPLAY_NAME)";
@@ -382,6 +369,7 @@
 					"@executable_path/Frameworks",
 				);
 				PRODUCT_NAME = CalculatorApp;
+				PROVISIONING_PROFILE_SPECIFIER = "";
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;
 			};
@@ -394,7 +382,9 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
+				DEVELOPMENT_TEAM = BR6WD3M6ZD;
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_KEY_CFBundleDisplayName = "$(PRODUCT_DISPLAY_NAME)";
@@ -406,6 +396,7 @@
 					"@executable_path/Frameworks",
 				);
 				PRODUCT_NAME = CalculatorApp;
+				PROVISIONING_PROFILE_SPECIFIER = "";
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_VERSION = 5.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -417,12 +408,15 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = BR6WD3M6ZD;
 				GENERATE_INFOPLIST_FILE = YES;
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.mycompany.CalculatorAppTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				PROVISIONING_PROFILE_SPECIFIER = "";
 				SWIFT_EMIT_LOC_STRINGS = NO;
 				SWIFT_VERSION = 5.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -434,12 +428,15 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = BR6WD3M6ZD;
 				GENERATE_INFOPLIST_FILE = YES;
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.mycompany.CalculatorAppTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				PROVISIONING_PROFILE_SPECIFIER = "";
 				SWIFT_EMIT_LOC_STRINGS = NO;
 				SWIFT_VERSION = 5.0;
 				TARGETED_DEVICE_FAMILY = "1,2";

src/tools/app_path.ts

@@ -148,16 +148,29 @@ async function _handleGetAppPathLogic(params: {
       nextStepsText = `Next Steps:
 1. Get bundle ID: get_macos_bundle_id({ appPath: "${appPath}" })
 2. Launch the app: launch_macos_app({ appPath: "${appPath}" })`;
-    } else if (params.platform === XcodePlatform.iOSSimulator) {
+    } else if (isSimulatorPlatform) {
       nextStepsText = `Next Steps:
-1. Get bundle ID: get_ios_bundle_id({ appPath: "${appPath}" })
+1. Get bundle ID: get_app_bundle_id({ appPath: "${appPath}" })
 2. Boot simulator: boot_simulator({ simulatorUuid: "SIMULATOR_UUID" })
 3. Install app: install_app_in_simulator({ simulatorUuid: "SIMULATOR_UUID", appPath: "${appPath}" })
 4. Launch app: launch_app_in_simulator({ simulatorUuid: "SIMULATOR_UUID", bundleId: "BUNDLE_ID" })`;
-    } else if (params.platform === XcodePlatform.iOS) {
+    } else if (
+      [
+        XcodePlatform.iOS,
+        XcodePlatform.watchOS,
+        XcodePlatform.tvOS,
+        XcodePlatform.visionOS,
+      ].includes(params.platform)
+    ) {
+      nextStepsText = `Next Steps:
+1. Get bundle ID: get_app_bundle_id({ appPath: "${appPath}" })
+2. Install app on device: install_app_device({ deviceId: "DEVICE_UDID", appPath: "${appPath}" })
+3. Launch app on device: launch_app_device({ deviceId: "DEVICE_UDID", bundleId: "BUNDLE_ID" })`;
+    } else {
+      // For other platforms
       nextStepsText = `Next Steps:
-1. Get bundle ID: get_ios_bundle_id({ appPath: "${appPath}" })
-2. Use Xcode to install the app on your connected iOS device`;
+1. The app has been built for ${params.platform}
+2. Use platform-specific deployment tools to install and run the app`;
     }
 
     return {
@@ -248,18 +261,22 @@ export function registerGetMacOSAppPathProjectTool(server: McpServer): void {
 }
 
 /**
- * Registers the get_ios_dev_app_path_ws tool
+ * Registers the get_device_app_path_ws tool
  */
-export function registerGetiOSDeviceAppPathWorkspaceTool(server: McpServer): void {
-  type Params = BaseWorkspaceParams & { configuration?: string };
+export function registerGetDeviceAppPathWorkspaceTool(server: McpServer): void {
+  type Params = BaseWorkspaceParams & { configuration?: string; platform?: string };
   registerTool<Params>(
     server,
-    'get_ios_dev_app_path_ws',
-    "Gets the app bundle path for an iOS physical device application using a workspace. IMPORTANT: Requires workspacePath and scheme. Example: get_ios_dev_app_path_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme' })",
+    'get_device_app_path_ws',
+    "Gets the app bundle path for a physical device application (iOS, watchOS, tvOS, visionOS) using a workspace. IMPORTANT: Requires workspacePath and scheme. Example: get_device_app_path_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme' })",
     {
       workspacePath: workspacePathSchema,
       scheme: schemeSchema,
       configuration: configurationSchema,
+      platform: z
+        .enum(['iOS', 'watchOS', 'tvOS', 'visionOS'])
+        .optional()
+        .describe('Target platform (defaults to iOS)'),
     },
     async (params: Params) => {
       const workspaceValidation = validateRequiredParam('workspacePath', params.workspacePath);
@@ -268,29 +285,40 @@ export function registerGetiOSDeviceAppPathWorkspaceTool(server: McpServer): voi
       const schemeValidation = validateRequiredParam('scheme', params.scheme);
       if (!schemeValidation.isValid) return schemeValidation.errorResponse!;
 
+      const platformMap: Record<string, XcodePlatform> = {
+        iOS: XcodePlatform.iOS,
+        watchOS: XcodePlatform.watchOS,
+        tvOS: XcodePlatform.tvOS,
+        visionOS: XcodePlatform.visionOS,
+      };
+
       return _handleGetAppPathLogic({
         ...params,
         configuration: params.configuration ?? 'Debug',
-        platform: XcodePlatform.iOS,
+        platform: platformMap[params.platform ?? 'iOS'],
         useLatestOS: true,
       });
     },
   );
 }
 
 /**
- * Registers the get_ios_dev_app_path_proj tool
+ * Registers the get_device_app_path_proj tool
  */
-export function registerGetiOSDeviceAppPathProjectTool(server: McpServer): void {
-  type Params = BaseProjectParams & { configuration?: string };
+export function registerGetDeviceAppPathProjectTool(server: McpServer): void {
+  type Params = BaseProjectParams & { configuration?: string; platform?: string };
   registerTool<Params>(
     server,
-    'get_ios_dev_app_path_proj',
-    "Gets the app bundle path for an iOS physical device application using a project file. IMPORTANT: Requires projectPath and scheme. Example: get_ios_dev_app_path_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })",
+    'get_device_app_path_proj',
+    "Gets the app bundle path for a physical device application (iOS, watchOS, tvOS, visionOS) using a project file. IMPORTANT: Requires projectPath and scheme. Example: get_device_app_path_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })",
     {
       projectPath: projectPathSchema,
       scheme: schemeSchema,
       configuration: configurationSchema,
+      platform: z
+        .enum(['iOS', 'watchOS', 'tvOS', 'visionOS'])
+        .optional()
+        .describe('Target platform (defaults to iOS)'),
     },
     async (params: Params) => {
       const projectValidation = validateRequiredParam('projectPath', params.projectPath);
@@ -299,10 +327,17 @@ export function registerGetiOSDeviceAppPathProjectTool(server: McpServer): void
       const schemeValidation = validateRequiredParam('scheme', params.scheme);
       if (!schemeValidation.isValid) return schemeValidation.errorResponse!;
 
+      const platformMap: Record<string, XcodePlatform> = {
+        iOS: XcodePlatform.iOS,
+        watchOS: XcodePlatform.watchOS,
+        tvOS: XcodePlatform.tvOS,
+        visionOS: XcodePlatform.visionOS,
+      };
+
       return _handleGetAppPathLogic({
         ...params,
         configuration: params.configuration ?? 'Debug',
-        platform: XcodePlatform.iOS,
+        platform: platformMap[params.platform ?? 'iOS'],
         useLatestOS: true,
       });
     },