Add iOS physical device discovery for testing workflows by cameroncooke · Pull Request #62 · getsentry/XcodeBuildMCP

cameroncooke · 2025-06-09T11:33:37Z

Summary

This PR adds the missing iOS physical device discovery capability that enables LLMs to effectively use the existing iOS device testing tools.

What's Added

list_ios_devices tool - Discovers connected physical iOS devices with UUIDs, names, and connection status
Modern + fallback support - Uses devicectl (iOS 17+/Xcode 15+) with xctrace fallback for compatibility
Proper integration - Registered in IOS_DEVICE_WORKFLOW and PROJECT_DISCOVERY tool groups
Clear separation - Focused solely on physical devices (complements existing list_sims for simulators)
Sectioned output - Organizes devices by availability status for easy LLM targeting

Why This is Needed

The existing iOS device testing infrastructure is excellent, but LLMs need to discover which physical devices are available before they can target them for testing. This tool provides that missing piece.

Before: LLMs couldn't discover physical devices to test against
After: LLMs can discover devices and use them with existing test tools

Example Usage

# Discover physical devices
list_ios_devices()

# Response shows available vs unavailable devices:
# Available Devices:
# - iPad Pro (12345678-1234-1234-1234-123456789ABC)
# - iPhone 15 Pro (87654321-4321-4321-4321-987654321DEF)

# Then use with existing test tools
test_ios_dev_ws({
  workspacePath: "/path/to/project.xcworkspace", 
  scheme: "MyScheme",
  deviceId: "12345678-1234-1234-1234-123456789ABC"
})

Design Decisions

Consistent format: Matches existing list_sims tool format (name + UUID in parentheses)
Status sections: Groups devices by "Available" vs "Unavailable" for clear LLM guidance
No simulator overlap: Focused purely on physical devices to avoid duplication with list_sims
Smart next steps: Only shows testing guidance when devices are actually available

Test Plan

Tool builds and registers successfully
Discovers physical iOS devices correctly
Handles devices in different states (available/unavailable)
Provides helpful guidance for next steps
Integrates cleanly with existing tool groups
No conflicts with existing simulator tools
Device IDs work correctly with test_ios_dev_ws tools

🤖 Generated with Claude Code

- Add device listing tool with devicectl/xctrace fallback - Enable LLMs to discover connected Apple devices before running tests - Register in iOS device workflow and project discovery groups - Supports all Apple platforms (iOS, iPadOS, watchOS, tvOS, visionOS) - Clean sectioned output showing available vs unavailable devices - Consistent naming with existing list_sims tool 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

Pull Request Overview

This PR adds iOS physical device discovery and testing capabilities while enhancing various device and build tool integrations and documentation. Key changes include:

Introducing a new tool (list_ios_devices) and updating tool-group registrations to support physical device management.
Modifying build utilities to support device-specific destination strings based on an optional deviceId parameter.
Enhancing test tools and updating documentation/configuration files to reflect the new device management and error response behavior.

Reviewed Changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test-multiblock-server.js	Added MCP server test tools for multiple content block responses.
src/utils/tool-groups.ts	Added a new group for physical DEVICE_MANAGEMENT.
src/utils/register-tools.ts	Updated tool registrations to add device test and log capture tools.
src/utils/build-utils.ts	Added optional deviceId handling for iOS, watchOS, tvOS, and visionOS build commands.
src/types/common.ts	Extended PlatformBuildOptions with an optional deviceId property.
src/tools/test_ios_device.ts / test_common.ts	Updated device test tools to require and pass deviceId in test workflows.
src/tools/device_log.ts	New module to capture and manage device logs using devicectl.
src/tools/bundleId.ts / src/tools/app_path.ts	Updated next-step instructions for device deployment.
Example project files and configuration updates	Updated bundle identifiers, signing, and project configuration for physical devices.
devices.txt, claude-code-multiblock-error-issue.md	Added sample device output and documented a known error response truncation issue.
TESTING_TASK_DOCUMENT.md and README.md	Updated testing documentation and added code signing instructions for device deployment.

Comments suppressed due to low confidence (1)

src/utils/build-utils.ts:149

Consider refactoring the repeated destination string construction logic for platforms with optional deviceId into a helper function. This will reduce duplication and improve maintainability across the similar branches for iOS, watchOS, tvOS, and visionOS.

if (platformOptions.deviceId) { destinationString = `platform=iOS,id=${platformOptions.deviceId}`; } else { destinationString = 'generic/platform=iOS'; }

cameroncooke · 2025-06-09T11:43:21Z

@codegen can you review this PR?

I'll review the PR for you! 🔎

💻 View my work

codegen-sh · 2025-06-09T11:45:34Z

🔍 PR Review Summary

I've completed a thorough review of this PR. Overall, this is an excellent addition that fills a critical gap in the XcodeBuildMCP ecosystem! 🎉

✅ Strengths

1. Addresses Real Need

Physical device discovery was indeed missing from the iOS device workflow
Complements existing simulator tools (list_sims) perfectly
Enables complete device-to-deployment pipeline

2. Robust Implementation

Modern + Fallback Strategy: Uses devicectl (iOS 17+/Xcode 15+) with xctrace fallback for compatibility
Comprehensive Device Info: Captures UDID, name, model, OS version, connection state, trust status
Smart Filtering: Excludes simulators, focuses on physical devices only
Error Handling: Graceful fallbacks and clear error messages

3. Excellent Integration

Properly registered in IOS_DEVICE_WORKFLOW and PROJECT_DISCOVERY tool groups
Consistent format with existing list_sims tool (name + UUID in parentheses)
Clear next-step guidance for discovered devices

4. Thorough Testing

Comprehensive testing document shows real-world validation
End-to-end workflow tested with actual iPhone 16 Pro Max
Edge cases and error scenarios documented

📋 Code Quality Observations

Device Discovery (src/tools/device.ts)

Clean TypeScript interfaces for device data structures
Proper JSON parsing with error handling
Smart platform detection logic
Good separation of concerns between devicectl and xctrace paths

Tool Registration (src/utils/register-tools.ts)

Correctly placed in appropriate tool groups
Proper environment variable configuration
Consistent with existing patterns

Documentation Updates

README properly updated with new device management section
Clear distinction between simulator and device workflows
Added code signing guidance (important for device deployment)

🎯 Minor Suggestions

Consider Device State Messaging: The current "Available/Unavailable" grouping is good, but you might consider adding more specific guidance for common states like "Device locked" or "Developer mode disabled"
Cleanup Opportunity: The testing documents (TESTING_TASK_DOCUMENT.md, claude-code-multiblock-error-issue.md, devices.txt, test-multiblock-server.js) appear to be development artifacts. Consider removing these before merge to keep the main branch clean.
Example Project Changes: The changes to example_projects/iOS_Calculator/ seem to be testing-related. Verify these should be included in the final PR.

🚀 Impact Assessment

This PR significantly enhances XcodeBuildMCP's capabilities:

Before: LLMs couldn't discover physical devices → workflow broken
After: Complete device discovery → build → deploy → test pipeline

The implementation is production-ready and follows established patterns in the codebase.

✅ Recommendation

APPROVE - This is a well-implemented, thoroughly tested feature that addresses a real gap in the iOS device workflow. The code quality is high and the integration is clean.

Suggested next steps:

Clean up development artifacts (testing docs, temp files)
Verify example project changes are intentional
Ready to merge! 🚀

codegen-sh · 2025-06-09T11:45:42Z

src/tools/device.ts

+            'List Devices (devicectl with JSON)',
+          );
+
+          if (result.success) {


👍 Excellent approach! Using devicectl with JSON output first, then falling back to xctrace ensures compatibility across different Xcode versions. This handles the transition period where teams might be on different Xcode versions.

codegen-sh · 2025-06-09T11:45:51Z

src/tools/device.ts

+                  device.visibilityClass === 'Simulator' ||
+                  !device.connectionProperties?.pairingState
+                ) {
+                  continue;


🛡️ Good defensive programming! Filtering out simulators and unpaired devices ensures the tool focuses on actual physical devices that are ready for deployment. This prevents confusion with simulator UUIDs.

codegen-sh · 2025-06-09T11:45:59Z

src/tools/device.ts

+            responseText += '🔗 Paired but Not Connected:\n';
+            for (const device of pairedDevices) {
+              responseText += `\n📱 ${device.name}\n`;
+              responseText += `   UDID: ${device.identifier}\n`;


📱 Love the sectioned output! Grouping devices by "Available", "Paired but Not Connected", and "Unpaired" gives LLMs clear guidance on which devices they can actually target for testing. The emoji indicators make it easy to scan.

codegen-sh · 2025-06-09T11:46:08Z

src/tools/device.ts

+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log('error', `Error listing devices: ${errorMessage}`);
+        return {
+          content: [


🎯 Smart next-step guidance! Only showing testing instructions when devices are actually available prevents LLMs from attempting operations on unavailable devices. The specific tool examples are very helpful.

codegen-sh · 2025-06-09T11:46:17Z

README.md

 > [!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


📚 Excellent addition! The code signing section is crucial for device deployment. Many developers struggle with this step, so having clear guidance upfront prevents frustration later in the workflow.

codegen-sh · 2025-06-09T11:46:29Z

✅ PR Review Complete!

I've thoroughly reviewed PR #62 and it's excellent work! 🎉

🌟 Key Highlights

Fills Critical Gap: Physical device discovery was the missing piece for complete iOS device workflows
Robust Implementation: Modern devicectl + xctrace fallback ensures broad compatibility
Smart Design: Sectioned output, clear device states, helpful next-step guidance
Thorough Testing: Real-world validation with iPhone 16 Pro Max documented

📝 Review Summary

✅ All checks passing
✅ Code quality is high with proper TypeScript interfaces and error handling
✅ Integration follows established patterns in the codebase
✅ Documentation properly updated with device management section

💡 Minor Cleanup Suggestions

Consider removing development artifacts (TESTING_TASK_DOCUMENT.md, claude-code-multiblock-error-issue.md, etc.) before merge
Verify example project changes are intentional

🚀 Impact

This PR transforms XcodeBuildMCP from having a broken device workflow to enabling complete Device Discovery → Build → Deploy → Test pipelines for LLMs.

Recommendation: APPROVE and ready to merge! 🎯

Great work on this feature - it's exactly what the ecosystem needed! 👏

💻 View my work • React 👍 or 👎

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

pauley-unsaturated · 2025-06-10T14:16:43Z

🎊 🥳

This was referenced Jun 9, 2025

feat: implement device log capture support #60

Closed

Add iOS physical device discovery for testing workflows #57

Closed

cameroncooke requested a review from Copilot June 9, 2025 11:37

Copilot AI reviewed Jun 9, 2025

View reviewed changes

codegen-sh bot reviewed Jun 9, 2025

View reviewed changes

cameroncooke force-pushed the pauley-unsaturated/ios_testing_ios_devices branch from dfa8b1c to da875c5 Compare June 9, 2025 14:20

cameroncooke merged commit fc872ca into main Jun 9, 2025
1 check passed

cameroncooke deleted the pauley-unsaturated/ios_testing_ios_devices branch June 9, 2025 14:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add iOS physical device discovery for testing workflows#62

Add iOS physical device discovery for testing workflows#62
cameroncooke merged 2 commits intomainfrom
pauley-unsaturated/ios_testing_ios_devices

cameroncooke commented Jun 9, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

cameroncooke commented Jun 9, 2025 •

edited by codegen-sh bot

Loading

Uh oh!

codegen-sh bot commented Jun 9, 2025

Uh oh!

codegen-sh bot Jun 9, 2025

Uh oh!

codegen-sh bot Jun 9, 2025

Uh oh!

codegen-sh bot Jun 9, 2025

Uh oh!

codegen-sh bot Jun 9, 2025

Uh oh!

codegen-sh bot Jun 9, 2025

Uh oh!

codegen-sh bot commented Jun 9, 2025

Uh oh!

Uh oh!

pauley-unsaturated commented Jun 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

cameroncooke commented Jun 9, 2025

Summary

What's Added

Why This is Needed

Example Usage

Design Decisions

Test Plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

cameroncooke commented Jun 9, 2025 • edited by codegen-sh bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codegen-sh bot commented Jun 9, 2025

🔍 PR Review Summary

✅ Strengths

📋 Code Quality Observations

🎯 Minor Suggestions

🚀 Impact Assessment

✅ Recommendation

Uh oh!

codegen-sh bot Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

codegen-sh bot Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

codegen-sh bot Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

codegen-sh bot Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

codegen-sh bot Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

codegen-sh bot commented Jun 9, 2025

✅ PR Review Complete!

🌟 Key Highlights

📝 Review Summary

💡 Minor Cleanup Suggestions

🚀 Impact

Uh oh!

Uh oh!

pauley-unsaturated commented Jun 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cameroncooke commented Jun 9, 2025 •

edited by codegen-sh bot

Loading