iOS Device Control

Un servidor MCP para controlar simuladores y dispositivos iOS reales, permitiendo la integración de asistentes de IA en macOS.

GitHub
8
Prueba este MCPPatrocinado

Documentación

iOS Device Control (chuk-mcp-ios)

Sistema integral de control de dispositivos iOS que admite tanto simuladores como dispositivos reales. Disponible como herramienta CLI independiente y como servidor MCP (Model Context Protocol) para integración con asistentes de IA.

Python 3.8+ License: MIT MCP Compatible

🚀 Características

  • 🎯 Gestión Unificada de Dispositivos: Controla simuladores iOS y dispositivos reales mediante una única interfaz
  • 📋 Gestión de Sesiones: Crea y gestiona sesiones de dispositivos para flujos de automatización organizados
  • 📱 Ciclo de Vida de Apps: Instala, lanza, termina y gestiona aplicaciones iOS
  • 🎮 Automatización de UI: Toca, desliza, escribe e interactúa con las interfaces de los dispositivos
  • 📸 Multimedia y Ubicación: Añade fotos/videos, simula ubicaciones GPS y rutas
  • 🔍 Depuración: Accede a registros, informes de fallos e información de depuración
  • 🤖 Servidor MCP: Integración con Claude y otros asistentes de IA
  • ⚡ Herramienta CLI: Interfaz de línea de comandos independiente para control directo

📋 Requisitos

Para Simuladores iOS (Principal)

  • macOS con Xcode instalado
  • Herramientas de Línea de Comandos de Xcode: xcode-select --install
  • Al menos un runtime de simulador iOS

Para Dispositivos Reales (Opcional)

  • Dispositivo iOS con Modo Desarrollador habilitado
  • Cuenta válida de Apple Developer (para instalación de apps)
  • Una o más de estas herramientas:
    • idb (Puente de Desarrollo iOS de Facebook) - Recomendado
    • devicectl (Xcode 15+)
    • instruments (Herramienta heredada de Xcode)

🔧 Instalación

Opción 1: Usando uv (Recomendado)

# Install with uv
uv add chuk-mcp-ios

# Run directly
uvx chuk-mcp-ios cli status

Opción 2: Usando pip

# Install from source
git clone https://github.com/yourusername/chuk-mcp-ios.git
cd chuk-mcp-ios
pip install -e .

# Or install from PyPI (when published)
pip install chuk-mcp-ios

Verificar Instalación

# Check system status
chuk-mcp-ios cli status

# Should show available tools and devices

⚠️ Estado Actual y Recomendaciones

Problemas Detectados en CLI

Según las pruebas, la CLI tiene varios errores que necesitan corrección:

  1. Resolución de Sesiones: Las sesiones aparecen activas pero los comandos no encuentran los dispositivos
  2. Errores de Importación: Falta la importación de time que causa fallos
  3. Resolución de Dispositivos: El uso directo de UDID también falla

Orden de Uso Recomendado

1. simctl directo (Más Fiable)

# Use native simulator tools directly
xcrun simctl list devices
xcrun simctl boot "iPhone 15" 
xcrun simctl io booted screenshot screenshot.png
xcrun simctl launch booted com.apple.Preferences

2. API de Python (Funciones Completas)

# Use the Python API directly for full functionality
python3 -c "
import asyncio
from chuk_mcp_ios.mcp.tools import ios_create_session, ios_screenshot
session = asyncio.run(ios_create_session())
print(f'Session: {session}')
"

3. Servidor MCP (Integración con IA)

# Use MCP server for AI assistant integration
uvx chuk-mcp-ios mcp
# Then connect via Claude or other AI assistants

4. CLI (Limitado, Tiene Errores)

# CLI currently has issues but basic commands work:
uvx chuk-mcp-ios cli status        # ✅ Works
uvx chuk-mcp-ios cli device list   # ✅ Works  
uvx chuk-mcp-ios cli session list  # ✅ Works
uvx chuk-mcp-ios cli ui screenshot # ❌ Broken
uvx chuk-mcp-ios cli app list      # ❌ Broken

Ejemplo Funcional Paso a Paso

Aquí tienes una secuencia completa que realmente funciona:

# 1. Check your system status
uvx chuk-mcp-ios cli status

# 2. List available devices to see what's available
uvx chuk-mcp-ios cli device list

# 3. Create a new session (this gives you a fresh session ID)
uvx chuk-mcp-ios cli session create --device "iPhone 15"
# Note: Copy the session ID from the output, e.g., session_1749425214_4b7f748f

# 4. List active sessions to verify
uvx chuk-mcp-ios cli session list

# 5. Use the actual session ID from step 3 for commands:
# Replace YOUR_SESSION_ID with the actual ID from step 3
uvx chuk-mcp-ios cli ui screenshot YOUR_SESSION_ID -o screenshot.png

# 6. Launch Settings app
uvx chuk-mcp-ios cli app launch YOUR_SESSION_ID com.apple.Preferences

# 7. Take another screenshot to see Settings
uvx chuk-mcp-ios cli ui screenshot YOUR_SESSION_ID -o settings.png

# 8. List installed apps
uvx chuk-mcp-ios cli app list YOUR_SESSION_ID

# 9. Clean up when done
uvx chuk-mcp-ios cli session terminate YOUR_SESSION_ID

Ejemplo Funcional (Con Soluciones Alternativas)

# Method 1: Try session ID first, fallback to UDID
SESSION_ID="session_1749425214_4b7f748f"
UDID="D5ABE678-7395-4EF6-880B-E649F4FEDEE5"

# Try session ID
uvx chuk-mcp-ios cli ui screenshot $SESSION_ID -o screenshot.png

# If that fails, try UDID directly
if [ $? -ne 0 ]; then
    echo "Session failed, trying UDID..."
    uvx chuk-mcp-ios cli ui screenshot $UDID -o screenshot.png
fi

# Method 2: Direct device approach (most reliable)
# Get UDID from device list
uvx chuk-mcp-ios cli device list
# Copy the UDID and use it directly
uvx chuk-mcp-ios cli ui screenshot D5ABE678-7395-4EF6-880B-E649F4FEDEE5 -o screenshot.png

# Method 3: Fresh session approach
# Clean slate approach if sessions are buggy
uvx chuk-mcp-ios cli session terminate session_1749425214_4b7f748f
uvx chuk-mcp-ios cli session terminate automation_1749424425_58872b30
NEW_SESSION=$(uvx chuk-mcp-ios cli quick-start | grep -o 'session_[a-zA-Z0-9_]*')
uvx chuk-mcp-ios cli ui screenshot $NEW_SESSION -o screenshot.png

Solución Inmediata para Tu Situación

# Based on your current sessions, try these in order:

# 1. Try direct UDID (most likely to work)
uvx chuk-mcp-ios cli ui screenshot D5ABE678-7395-4EF6-880B-E649F4FEDEE5 -o screenshot.png

# 2. If UDID doesn't work, test direct simctl
xcrun simctl io D5ABE678-7395-4EF6-880B-E649F4FEDEE5 screenshot test.png

# 3. If simctl works but CLI doesn't, it's a CLI bug
# Use Python API as workaround:
python3 -c "
import asyncio
from chuk_mcp_ios.mcp.tools import ios_screenshot
result = asyncio.run(ios_screenshot('D5ABE678-7395-4EF6-880B-E649F4FEDEE5', 'screenshot.png'))
print('Success!' if result.get('success') else f'Error: {result.get(\"error\")}')
"

Alternativa: Usar Inicio Rápido

# Auto-setup with best available device
uvx chuk-mcp-ios cli quick-start

# This creates a session and tells you the ID to use
# Then use that ID for subsequent commands

📚 Ejemplos de CLI

Primero, comprueba qué comandos están realmente disponibles:

# Check main commands
chuk-mcp-ios cli --help

# Check UI subcommands
chuk-mcp-ios cli ui --help

# Check device subcommands  
chuk-mcp-ios cli device --help

# Check session subcommands
chuk-mcp-ios cli session --help

# Check app subcommands
chuk-mcp-ios cli app --help

Gestión de Dispositivos

# List all available devices (simulators + real devices)
chuk-mcp-ios cli device list

# List only simulators
chuk-mcp-ios cli device list --type simulator

# Show device details
chuk-mcp-ios cli device info DEVICE_UDID

# Boot a specific simulator
chuk-mcp-ios cli device boot DEVICE_UDID

# Shutdown simulator
chuk-mcp-ios cli device shutdown DEVICE_UDID

Gestión de Sesiones

# Create session with auto-selected device
chuk-mcp-ios cli session create

# Create session with specific device name
chuk-mcp-ios cli session create --device "iPhone 15"

# Create session with specific UDID
chuk-mcp-ios cli session create --udid ABCD-1234-EFGH-5678

# List active sessions
chuk-mcp-ios cli session list

# Terminate session
chuk-mcp-ios cli session terminate session_123

Gestión de Apps

# List installed apps
chuk-mcp-ios cli app list session_123

# List only user apps (exclude system apps)
chuk-mcp-ios cli app list session_123 --user-only

# Install app from .app bundle
chuk-mcp-ios cli app install session_123 /path/to/MyApp.app

# Launch app by bundle ID
chuk-mcp-ios cli app launch session_123 com.example.myapp

# Terminate running app
chuk-mcp-ios cli app terminate session_123 com.example.myapp

# Uninstall app
chuk-mcp-ios cli app uninstall session_123 com.example.myapp

Automatización de UI

# Take screenshot
chuk-mcp-ios cli ui screenshot session_123 -o /path/to/screenshot.png

# Tap at coordinates
chuk-mcp-ios cli ui tap session_123 100 200

# Type text (available commands based on your CLI implementation)
chuk-mcp-ios cli ui type session_123 "Hello World"

# Check available UI commands
chuk-mcp-ios cli ui --help

Nota: Los comandos exactos de UI disponibles dependen de tu implementación de CLI. Consulta chuk-mcp-ios cli ui --help para la lista completa.

Multimedia y Ubicación

# Note: Check available commands with --help first
chuk-mcp-ios cli --help

# Location and media commands may be available under different subcommands
# Check for location commands:
chuk-mcp-ios cli location --help  # if location subcommand exists
chuk-mcp-ios cli media --help     # if media subcommand exists

# If not available via CLI, use Python API:
python3 -c "
from chuk_mcp_ios.core.media_manager import UnifiedMediaManager
media = UnifiedMediaManager()
media.set_location_by_name('your_session_id', 'San Francisco')
"

Encontrar Comandos Disponibles

La estructura de la CLI puede diferir de esta documentación. Comprueba siempre los comandos disponibles:

# Discover main command structure
chuk-mcp-ios cli --help

# Check subcommands for each area
chuk-mcp-ios cli device --help
chuk-mcp-ios cli session --help  
chuk-mcp-ios cli app --help
chuk-mcp-ios cli ui --help

# If certain commands aren't available in CLI, they may be:
# 1. Available only via MCP tools
# 2. Available only via Python API
# 3. Named differently than documented

# Example: Check what UI commands actually exist
chuk-mcp-ios cli ui --help
# Output might show: tap, screenshot, type (but not press, swipe, etc.)

Alternativas de Comandos:

# If CLI command doesn't exist, try Python API:
python3 -c "
import asyncio
from chuk_mcp_ios.mcp.tools import ios_press_button
result = asyncio.run(ios_press_button('session_123', 'home'))
print(result)
"

# Or check if it's an MCP-only feature
chuk-mcp-ios mcp  # Start MCP server and use via AI assistant

🤖 Uso del Servidor MCP

Iniciar el Servidor MCP

# Start MCP server (stdio mode)
chuk-mcp-ios mcp

# Start with specific configuration
chuk-mcp-ios mcp --host localhost --port 8080

# With debug logging
chuk-mcp-ios mcp --log-level DEBUG

Integración con Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ios-control": {
      "command": "uvx",
      "args": ["chuk-mcp-ios", "mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Ejemplos de Lenguaje Natural con MCP

Una vez conectado a Claude, puedes usar lenguaje natural:

🧑 "Take a screenshot of the current iOS simulator"
🤖 I'll take a screenshot for you...
   ✅ Screenshot saved to screenshot_20231215_143022.png

🧑 "Launch the Settings app and navigate to WiFi settings"
🤖 I'll launch Settings and help you navigate...
   ✅ Settings app launched
   ✅ Tapped on WiFi settings

🧑 "Set the device location to Tokyo and open Maps"
🤖 Setting location to Tokyo and opening Maps...
   ✅ Location set to Tokyo, Japan (35.6762, 139.6503)
   ✅ Maps app launched

🧑 "Install the app at /Users/me/MyApp.app and launch it"
🤖 I'll install and launch the app for you...
   ✅ App MyApp installed successfully
   ✅ App launched: com.example.myapp

🧑 "Simulate a user scrolling through a photo gallery"
🤖 I'll simulate scrolling through photos...
   ✅ Photos app launched
   ✅ Performed swipe gestures to scroll through gallery

Herramientas MCP Disponibles

El servidor MCP proporciona estas herramientas:

// Session Management
ios_create_session()
ios_list_sessions()
ios_terminate_session()

// Device Control  
ios_list_devices()
ios_boot_device()
ios_shutdown_device()

// App Management
ios_install_app()
ios_launch_app()
ios_terminate_app()
ios_uninstall_app()
ios_list_apps()

// UI Automation
ios_tap()
ios_double_tap()
ios_long_press()
ios_swipe()
ios_swipe_direction()
ios_input_text()
ios_press_button()
ios_screenshot()
ios_record_video()
ios_get_screen_info()

// Media & Location
ios_set_location()
ios_set_location_by_name()
ios_add_media()

// Utilities
ios_open_url()
ios_set_status_bar()
ios_set_appearance()
ios_clear_keychain()
ios_get_logs()
ios_set_permission()
ios_focus_simulator()

🐍 Uso de la API de Python

Uso Básico

from chuk_mcp_ios.core.device_manager import UnifiedDeviceManager
from chuk_mcp_ios.core.session_manager import UnifiedSessionManager
from chuk_mcp_ios.core.ui_controller import UnifiedUIController

# Initialize managers
device_manager = UnifiedDeviceManager()
session_manager = UnifiedSessionManager()
ui_controller = UnifiedUIController()

# Set up session manager for UI controller
ui_controller.set_session_manager(session_manager)

# Create automation session
session_id = session_manager.create_automation_session()
print(f"Created session: {session_id}")

# Take screenshot
screenshot_path = ui_controller.take_screenshot(session_id, "test.png")
print(f"Screenshot saved: {screenshot_path}")

# Interact with UI
ui_controller.tap(session_id, 100, 200)
ui_controller.swipe_up(session_id)
ui_controller.input_text(session_id, "Hello World")

# Clean up
session_manager.terminate_session(session_id)

Ejemplo Avanzado de Automatización

from chuk_mcp_ios.core import *
import time

async def automate_app_testing():
    """Example: Automated app testing workflow."""
    
    # Initialize managers
    device_mgr = UnifiedDeviceManager()
    session_mgr = UnifiedSessionManager()
    app_mgr = UnifiedAppManager()
    ui_ctrl = UnifiedUIController()
    
    # Link managers
    app_mgr.set_session_manager(session_mgr)
    ui_ctrl.set_session_manager(session_mgr)
    
    try:
        # Create session with iPhone simulator
        session_id = session_mgr.create_automation_session({
            'device_name': 'iPhone 15'
        })
        
        # Install test app
        app_info = app_mgr.install_app(
            session_id, 
            '/path/to/TestApp.app',
            AppInstallConfig(launch_after_install=True)
        )
        
        # Wait for app to load
        time.sleep(3)
        
        # Take screenshot of app launch
        ui_ctrl.take_screenshot(session_id, 'app_launch.png')
        
        # Perform test interactions
        ui_ctrl.tap(session_id, 200, 300)  # Tap login button
        ui_ctrl.input_text(session_id, 'test@example.com')
        ui_ctrl.tap(session_id, 200, 400)  # Tap password field
        ui_ctrl.input_text(session_id, 'password123')
        ui_ctrl.tap(session_id, 200, 500)  # Tap submit
        
        # Wait and verify
        time.sleep(2)
        ui_ctrl.take_screenshot(session_id, 'after_login.png')
        
        # Get app logs
        logs = logger_mgr.get_app_logs(session_id, app_info.bundle_id)
        print(f"Found {len(logs)} log entries")
        
    finally:
        # Clean up
        if 'session_id' in locals():
            session_mgr.terminate_session(session_id)

# Run the automation
import asyncio
asyncio.run(automate_app_testing())

📱 Configuración de Dispositivos Reales

Requisitos Previos

  1. Habilitar Modo Desarrollador (iOS 16+):

    • Conecta el dispositivo al Mac con Xcode
    • Ajustes → Privacidad y Seguridad → Modo Desarrollador
    • Actívalo y reinicia el dispositivo

  2. Instalar idb (Recomendado):

    # Using Homebrew
brew install idb-companion

# Using pip
pip install fb-idb

  3. Confiar en el Ordenador:

    • Conecta el dispositivo por USB
    • Toca "Confiar" cuando se te solicite en el dispositivo

Ejemplos con Dispositivos Reales

# List real devices
chuk-mcp-ios cli device list --type real

# Create session with real iPhone
chuk-mcp-ios cli session create --device "Chris's iPhone"

# Install app (requires developer certificate)
chuk-mcp-ios cli app install session_123 MyApp.ipa

# Same UI automation works on real devices
chuk-mcp-ios cli ui screenshot session_123 -o real_device.png

🔧 Configuración

Variables de Entorno

# Tool paths (if not in PATH)
export IOS_CONTROL_SIMCTL_PATH="/usr/bin/xcrun simctl"
export IOS_CONTROL_IDB_PATH="/usr/local/bin/idb"
export IOS_CONTROL_DEVICECTL_PATH="/usr/bin/xcrun devicectl"

# Timeouts
export IOS_CONTROL_DEFAULT_TIMEOUT=30
export IOS_CONTROL_BOOT_TIMEOUT=60

# Logging
export IOS_CONTROL_LOG_LEVEL=INFO
export IOS_CONTROL_LOG_DIR="$HOME/.ios-control/logs"

Archivo de Configuración

Crea ~/.ios-control/config.yaml:

defaults:
  timeout: 30
  screenshot_format: png
  
devices:
  preferred_simulator: "iPhone 15 Pro"
  auto_boot: true
  
logging:
  level: INFO
  file_logging: true
  
mcp:
  host: localhost
  port: 8080

📊 Ejemplos y Demostraciones

Ejecutar Demos Integradas

# Interactive demo (menu-driven)
python -m chuk_mcp_ios.examples.interactive_demo

# Automated end-to-end demo
python -m chuk_mcp_ios.examples.automated_demo

# MCP server demonstration
python -m chuk_mcp_ios.examples.e2e_mcp_demo

# Web scraping demo (Techmeme)
python -m chuk_mcp_ios.examples.techmeme --auto

Scripts de Automatización Personalizados

# examples/custom_automation.py
from chuk_mcp_ios import *

def test_settings_navigation():
    """Test navigating through iOS Settings."""
    with AutomationSession() as session:
        # Launch Settings
        session.launch_app('com.apple.Preferences')
        session.screenshot('settings_main.png')
        
        # Navigate to WiFi
        session.tap_text('Wi-Fi')
        session.screenshot('wifi_settings.png')
        
        # Navigate back
        session.tap_back_button()
        session.screenshot('settings_back.png')

if __name__ == "__main__":
    test_settings_navigation()

🏗️ Arquitectura

chuk-mcp-ios/
├── core/                   # Core functionality (device-agnostic)
│   ├── base.py            # Base classes and interfaces
│   ├── device_manager.py  # Unified device management
│   ├── session_manager.py # Session lifecycle management
│   ├── app_manager.py     # App installation and control
│   ├── ui_controller.py   # UI automation and gestures
│   ├── media_manager.py   # Photos, videos, and location
│   ├── logger_manager.py  # Logging and crash reports
│   └── utilities_manager.py # Misc utilities and settings
├── devices/               # Device-specific implementations
│   ├── simulator.py       # iOS Simulator support
│   ├── real_device.py     # Real device support
│   └── detector.py        # Device discovery and detection
├── mcp/                   # MCP server implementation
│   ├── tools.py          # MCP tool definitions
│   ├── models.py         # Pydantic models for validation
│   └── main.py           # MCP server entry point
├── cli/                   # Command-line interface
│   └── main.py           # CLI entry point and commands
└── examples/              # Usage examples and demos
    ├── interactive_demo.py
    ├── automated_demo.py
    ├── e2e_mcp_demo.py
    └── techmeme.py

🧪 Desarrollo

Configurar el Entorno de Desarrollo

# Clone repository
git clone https://github.com/yourusername/chuk-mcp-ios.git
cd chuk-mcp-ios

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Or with uv
uv sync --dev

Ejecutar Pruebas

# Run all tests
pytest

# Run with coverage
pytest --cov=chuk_mcp_ios

# Run specific test file
pytest tests/test_device_manager.py

# Run integration tests (requires simulators)
pytest tests/integration/ -m "not slow"

Calidad del Código

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Type checking
mypy src/

# Lint
flake8 src/

Añadir Nuevas Funcionalidades

  1. Añade interfaces a core/base.py
  2. Implementa la funcionalidad en el módulo principal correspondiente
  3. Añade la herramienta MCP en mcp/tools.py con la validación adecuada
  4. Añade el comando CLI en cli/main.py
  5. Escribe pruebas en tests/
  6. Añade ejemplos en examples/
  7. Actualiza la documentación

🐛 Solución de Problemas

Problemas Conocidos Actuales

Múltiples Problemas de CLI Identificados:

  1. Error de Resolución de Sesiones: Las sesiones aparecen activas pero no se pueden usar
  2. Error de Importación Faltante: name 'time' is not defined
  3. Error de Resolución de Dispositivos: Los UUID tampoco funcionan
# These errors indicate code-level issues:
uvx chuk-mcp-ios cli app list session_1749426020_9ff9470b
# ❌ Failed: Device not found: session_1749426020_9ff9470b

uvx chuk-mcp-ios cli app list 45007866-72A3-4ACD-AD98-7EC58A726372  
# ❌ Failed: name 'time' is not defined

Soluciones Alternativas Inmediatas

Opción 1: Usar Comandos simctl Directos

# Bypass the CLI entirely and use simctl directly
UDID="45007866-72A3-4ACD-AD98-7EC58A726372"

# Take screenshot
xcrun simctl io $UDID screenshot screenshot.png

# Launch app
xcrun simctl launch $UDID com.apple.Preferences

# List installed apps (basic)
xcrun simctl listapps $UDID

# Boot device if needed
xcrun simctl boot $UDID

Opción 2: Usar la API de Python Directamente

# Create a simple Python script to bypass CLI issues
cat << 'EOF' > ios_test.py
#!/usr/bin/env python3
import asyncio
import sys
import os
sys.path.insert(0, '.')

async def main():
    from chuk_mcp_ios.mcp.tools import (
        ios_list_devices, 
        ios_create_session, 
        ios_screenshot,
        ios_list_apps
    )
    
    # List devices
    print("=== Devices ===")
    devices = await ios_list_devices()
    print(devices)
    
    # Create session
    print("\n=== Creating Session ===")
    session = await ios_create_session(device_name="iPhone 15")
    if 'error' in session:
        print(f"Error: {session['error']}")
        return
    
    session_id = session['session_id']
    print(f"Session: {session_id}")
    
    # Take screenshot
    print("\n=== Screenshot ===")
    screenshot = await ios_screenshot(session_id, "test.png")
    print(screenshot)
    
    # List apps
    print("\n=== Apps ===")
    apps = await ios_list_apps(session_id)
    print(f"Found {len(apps.get('apps', []))} apps")

if __name__ == "__main__":
    asyncio.run(main())
EOF

python3 ios_test.py

Opción 3: Uso del Servidor MCP (Más Fiable)

# Start MCP server in one terminal
uvx chuk-mcp-ios mcp

# In another terminal or via AI assistant, use MCP tools
# This bypasses the CLI entirely and uses the core MCP functions

Operaciones Manuales con Dispositivos

Control Directo del Simulador (Siempre Funciona):

# List all simulators
xcrun simctl list devices

# Boot a specific simulator
xcrun simctl boot "iPhone 15"

# Take screenshot
xcrun simctl io booted screenshot screenshot.png

# Launch Settings
xcrun simctl launch booted com.apple.Preferences

# Add media
xcrun simctl addmedia booted ~/Desktop/*.jpg

# Set location
xcrun simctl location booted set 37.7749,-122.4194

Depurar los Problemas de CLI

Para ayudar a identificar los problemas:

# 1. Check if core imports work
python3 -c "
try:
    from chuk_mcp_ios.core.device_manager import UnifiedDeviceManager
    print('✅ Core imports work')
except Exception as e:
    print(f'❌ Import error: {e}')
"

# 2. Check if time import is missing somewhere
python3 -c "
import chuk_mcp_ios.core.app_manager
print('✅ App manager imports work')
"

# 3. Minimal device test
python3 -c "
from chuk_mcp_ios.core.device_manager import UnifiedDeviceManager
dm = UnifiedDeviceManager()
devices = dm.discover_all_devices()
print(f'Found {len(devices)} devices')
for d in devices:
    print(f'  {d.name}: {d.udid}')
"

Problemas Conocidos y Soluciones Alternativas

Problema de Resolución de ID de Sesión: Si las sesiones aparecen como activas pero los comandos fallan, podría ser un error en la resolución de sesión a dispositivo:

# Workaround 1: Use device UDID directly (bypass sessions)
# Get UDID from session list, then use it directly
UDID="D5ABE678-7395-4EF6-880B-E649F4FEDEE5"  # From session list
uvx chuk-mcp-ios cli ui screenshot $UDID -o screenshot.png

# Workaround 2: Use quick-start for guaranteed working session
uvx chuk-mcp-ios cli quick-start
# Use the session ID that quick-start returns

# Workaround 3: Python API bypass (if CLI has issues)
python3 -c "
import asyncio
from chuk_mcp_ios.mcp.tools import ios_screenshot
result = asyncio.run(ios_screenshot('session_1749425214_4b7f748f', 'screenshot.png'))
print(result)
"

Comandos Verificados que Funcionan

Estos comandos deberían funcionar definitivamente:

# 1. System check (always works)
uvx chuk-mcp-ios cli status

# 2. Device listing (always works)
uvx chuk-mcp-ios cli device list

# 3. Direct device operations (bypass sessions)
# Use UDID from device list directly
uvx chuk-mcp-ios cli device info DEVICE_UDID

# 4. Session management (metadata operations)
uvx chuk-mcp-ios cli session list
uvx chuk-mcp-ios cli session create --device "iPhone 15"
uvx chuk-mcp-ios cli session terminate SESSION_ID

Pasos para Solucionar Problemas

# Step 1: Verify simulator is actually running
xcrun simctl list devices | grep Booted

# Step 2: Test direct simctl access
xcrun simctl io D5ABE678-7395-4EF6-880B-E649F4FEDEE5 screenshot direct_test.png

# Step 3: If direct simctl works but CLI doesn't, it's a session resolution bug
# Report this as an issue and use direct UDID as workaround

# Step 4: Clean restart if needed
uvx chuk-mcp-ios cli session terminate --all  # if available
# Or manually terminate each session
uvx chuk-mcp-ios cli session terminate session_1749425214_4b7f748f
uvx chuk-mcp-ios cli session terminate automation_1749424425_58872b30

Dispositivo No Encontrado:

# Problem: No devices available
# Solution: Check simulators and boot one

# List available devices
uvx chuk-mcp-ios cli device list

# Boot a simulator if none are running
uvx chuk-mcp-ios cli device boot DEVICE_UDID_FROM_LIST

# Then create session
uvx chuk-mcp-ios cli session create --udid DEVICE_UDID_FROM_LIST

Comando No Encontrado:

# Problem: Command like 'press' doesn't exist
# Solution: Check available commands

uvx chuk-mcp-ios cli ui --help  # See actual UI commands
uvx chuk-mcp-ios cli --help     # See all available commands

# Many advanced features are MCP-only or Python API-only

Obtener Ayuda

  1. Comprueba el estado del sistema: chuk-mcp-ios cli status
  2. Revisa los registros: ~/.ios-control/logs/
  3. Ejecuta diagnósticos: chuk-mcp-ios cli diagnose
  4. Consulta los problemas de GitHub: Página de Problemas

🤝 Contribuciones

¡Aceptamos contribuciones! Así es como empezar:

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Haz tus cambios con pruebas
  4. Formatea el código (black, isort)
  5. Prueba a fondo (pytest)
  6. Haz commit de los cambios (git commit -m 'Add amazing feature')
  7. Haz push de la rama (git push origin feature/amazing-feature)
  8. Abre una Solicitud de Extracción

Directrices de Contribución

  • Añade pruebas para nuevas funcionalidades
  • Actualiza la documentación
  • Sigue el estilo de código existente
  • Añade ejemplos para funcionalidades complejas
  • Actualiza el registro de cambios

📄 Licencia

Licencia MIT - consulta el archivo LICENCIA para más detalles

🙏 Agradecimientos

  • Apple por el Simulador iOS y las herramientas de desarrollo
  • Facebook por idb (Puente de Desarrollo iOS)
  • Anthropic por MCP (Model Context Protocol)
  • Comunidad de código abierto por las herramientas y bibliotecas utilizadas

📞 Soporte

Hecho con ❤️ para la automatización de iOS y la integración con IA