xcode-mcp

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona herramientas para operaciones relacionadas con Xcode, lo que facilita el trabajo con proyectos Xcode desde clientes MCP como Claude Desktop. El servidor ofrece diversas utilidades para la gestión de proyectos Xcode, la creación, las pruebas, el archivado, la firma de código y otras herramientas de desarrollo para iOS.

Características

• Recuperación de información del proyecto Xcode y listado de esquemas
• Capacidades de compilación mejoradas con opciones de salida limpias y personalizadas
• Ejecución de pruebas integral con control granular
• Archivado de aplicaciones y exportación de IPA para distribución
• Gestión de perfiles de aprovisionamiento y firma de código
• Integración de Swift Package Manager
• Gestión del simulador de iOS mediante simctl
• NUEVO: Implementación y lanzamiento de aplicaciones en dispositivos reales con detección automática de instalación de Xcode y administración mejorada de dispositivos
• Manejo inteligente de errores de instalación de aplicaciones con reintento automático
• Almacenamiento en caché inteligente de información del dispositivo y de Xcode para un mejor rendimiento

Instalación

Uso

Uso con Claude Desktop

1. Abra el archivo de configuración de Claude Desktop:
   # macOS open ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Agregue o modifique la siguiente configuración:
   { "mcpServers": { "xcode-mcp": { "command": "npx", "args": [ "@devyhan/xcode-mcp", "-y" ] } } }
3. Reinicie Claude Desktop.

Herramientas disponibles

1. información del proyecto xcode

Recupera información detallada sobre un proyecto o espacio de trabajo de Xcode, incluidos objetivos, configuraciones y esquemas.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)

Ejemplo :

Salida de muestra :

2. esquemas de lista de xcode

Proporciona una lista completa de todos los esquemas, objetivos y configuraciones disponibles en un proyecto o espacio de trabajo de Xcode.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)

Ejemplo :

Salida de muestra :

3. xcode-build

Crea un proyecto o espacio de trabajo de Xcode con opciones mejoradas. Admite compilaciones de proyectos y espacios de trabajo, compilaciones limpias y directorios de salida personalizados.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)
• scheme (obligatorio): El esquema para construir
• configuration (opcional): Configuración de compilación (por ejemplo, Depuración, Versión)
• destination (opcional): destino de compilación (por ejemplo, 'plataforma=iOS Simulator,nombre=iPhone 14')
• extraArgs (opcional): argumentos adicionales de xcodebuild como una matriz de cadenas
• outputDir (opcional): directorio de salida de compilación personalizado (SYMROOT)
• clean (opcional): si se debe realizar una compilación limpia (predeterminado: falso)

Ejemplo :

Comando generado :

4. prueba de xcode

Ejecuta pruebas para un proyecto o espacio de trabajo de Xcode con amplias opciones. Proporciona un control preciso sobre la ejecución de pruebas, incluyendo la ejecución de pruebas específicas, planes de prueba y diversos modos de prueba.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)
• scheme (obligatorio): El esquema a probar
• destination (obligatorio): destino de la prueba (p. ej., 'plataforma=iOS Simulator,nombre=iPhone 14')
• testPlan (opcional): Nombre del plan de prueba a utilizar
• onlyTesting (opcional): Matriz de identificadores de prueba específicos para ejecutar
• skipTesting (opcional): Matriz de identificadores de prueba para omitir
• resultBundlePath (opcional): Ruta para guardar el paquete de resultados de la prueba
• buildForTesting (opcional): compilar solo para probar sin ejecutar pruebas
• testWithoutBuilding (opcional): ejecuta pruebas sin compilar

Ejemplo :

Comando generado :

5. archivo xcode

Crea un archivo (.xcarchive) de un proyecto de Xcode y, opcionalmente, lo exporta a un archivo IPA para su distribución. Compatible con los métodos de distribución de App Store, ad-hoc y empresariales mediante la opción de exportación plist.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)
• scheme (obligatorio): El esquema a archivar
• configuration (opcional): Configuración de compilación (por ejemplo, versión)
• archivePath (obligatorio): Ruta para guardar el archivo .xcarchive
• exportPath (opcional): Ruta para exportar el archivo (por ejemplo, archivo IPA)
• exportOptionsPlist (opcional): Ruta al archivo exportOptions.plist

Ejemplo :

Comandos generados :

6. información de diseño de código de xcode

Recupera información completa sobre la firma de código y los perfiles de aprovisionamiento de un proyecto de Xcode. Muestra las identidades de firma de código instaladas, la configuración de firma de código del proyecto y los perfiles de aprovisionamiento en el sistema.

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)
• target (opcional): nombre del objetivo específico

Ejemplo :

Salida de muestra :

7. administrador de paquetes swift

Proporciona acceso a la funcionalidad del Gestor de Paquetes Swift (SPM) para gestionar paquetes Swift. Admite comandos comunes de SPM como init, update, resolve, reset y clean.

Parámetros :

• command (obligatorio): comando SPM a ejecutar ("init", "update", "resolve", "reset", "clean")
• packageDir (obligatorio): Ruta del directorio del paquete Swift
• extraArgs (opcional): argumentos SPM adicionales como una matriz de cadenas

Ejemplo :

Comando generado :

Salida de muestra :

8. simctl-manager

Proporciona acceso a las funciones de gestión del simulador de iOS mediante la herramienta de línea de comandos simctl . Permite listar, crear, iniciar, instalar aplicaciones y gestionar dispositivos del simulador.

Parámetros :

• command (obligatorio): comando SimCtl ("lista", "crear", "arrancar", "apagar", "borrar", "instalar", "iniciar", "eliminar")
• extraArgs (opcional): argumentos simctl adicionales como una matriz de cadenas

Ejemplo :

Comando generado :

Ejemplo de salida (abreviado) :

9. ejecutar en el dispositivo

Crea, instala y ejecuta una aplicación en un dispositivo iOS físico. Admite el nombre del dispositivo (incluidos los nombres en coreano) o UUID para la selección del dispositivo, las variables de entorno y la transmisión de registros. Ahora con especificación directa de bundleId, opción para omitir la compilación y argumentos de lanzamiento adicionales .

Parámetros :

• projectPath (obligatorio): ruta al proyecto Xcode (.xcodeproj) o al espacio de trabajo (.xcworkspace)
• scheme (obligatorio): El esquema para construir y ejecutar
• device (obligatorio): identificador o nombre del dispositivo (admite nombres coreanos)
• configuration (opcional): Configuración de compilación (por ejemplo, Depuración, Versión)
• streamLogs (opcional): si se deben transmitir los registros del dispositivo después del lanzamiento
• startStopped (opcional): si se debe iniciar la aplicación en un estado de pausa para adjuntarla al depurador
• environmentVars (opcional): Variables de entorno para pasar a la aplicación (formato clave1=valor1,clave2=valor2)
• xcodePath (opcional): ruta de la aplicación Xcode (predeterminado: "/Applications/Xcode-16.2.0.app")
• listDevices (opcional): muestra todos los dispositivos detectados con sus ID antes de ejecutarse
• skipBuild (opcional): omite el paso de compilación e instalación para aplicaciones ya instaladas
• extraLaunchArgs (opcional): argumentos adicionales para pasar al comando de lanzamiento devicectl
• directBundleId (opcional): especifica directamente el ID del paquete en lugar de extraerlo del proyecto

Ejemplo :

Proceso :

1. La herramienta identifica tanto el UDID de Xcode como el UUID de CoreDevice para el dispositivo especificado
2. Utiliza el UDID de Xcode para crear e instalar la aplicación.
3. Utiliza el UUID de CoreDevice para iniciar la aplicación con devicectl
4. Recupera el identificador del paquete de la aplicación.
5. Si se solicita, transmite los registros del dispositivo.

Mejoras clave en la versión v0.4.0 :

• Capacidad de especificar bundleId directamente sin necesidad de un proyecto
• Omitir el paso de compilación e instalación para aplicaciones ya instaladas
• Compatibilidad con argumentos adicionales del comando de lanzamiento devicectl
• Mejor visualización de la información del modelo del dispositivo y de la versión del sistema operativo
• Manejo de rutas y registro mejorados para comandos devicectl

Salida de muestra :

Ejemplo de escenario: uso con LLM

A continuación se muestra un ejemplo de cómo se podría incentivar a un LLM como Claude a utilizar estas herramientas en secuencia:

Mensaje de usuario a Claude:

Flujo de trabajo esperado:

1. Claude ejecutará la herramienta xcode-list-schemes para recuperar todos los esquemas:
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
2. Claude ejecutará la herramienta xcode-test con el esquema identificado:
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: [First scheme from output] Destination: platform=iOS Simulator,name=iPhone 14
3. Luego, Claude usará la herramienta xcode-archive para crear un archivo:
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: [First scheme from output] Configuration: Release ArchivePath: /Users/username/Desktop/MyApp.xcarchive

Este flujo de trabajo demuestra cómo encadenar varias herramientas, utilizando la salida de una herramienta para informar los parámetros de otra.

Ejemplo: Ejecución en un dispositivo real

Mensaje de usuario a Claude:

Flujo de trabajo esperado:

1. Claude primero obtendrá la lista de dispositivos:
   listDevices: true
2. Claude identificará su dispositivo físico y ejecutará la aplicación en él:
   Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj Scheme: MyApp Device: "Your iPhone" (or the device UUID) StreamLogs: true
3. Para un relanzamiento rápido sin necesidad de reconstruir:
   Device: "Your iPhone" DirectBundleId: "com.example.myapp" SkipBuild: true

Consideraciones de seguridad

Esta herramienta puede ejecutar comandos relacionados con Xcode, lo que supone riesgos de seguridad. Nota:

• Úselo solo con proyectos Xcode confiables.
• Tenga cuidado con los proyectos de fuentes desconocidas.
• No incluya información confidencial en los parámetros de compilación.

Desarrollo

Requisitos

• Node.js 16 o superior
• npm 6 o superior
• Xcode 14 o superior (para todas las funciones)
• Xcode 16 o superior (necesario para devicectl y funciones del dispositivo real)

Desarrollo y pruebas locales

Licencia

Instituto Tecnológico de Massachusetts (MIT)