Xcode MCP

Integra con Xcode para construir y gestionar tus proyectos.

Documentación

Servidor Xcode MCP

Un servidor MCP (Protocolo de Contexto del Modelo) que proporciona una integración completa con Xcode para asistentes de IA. Este servidor permite a los agentes de IA interactuar con proyectos de Xcode, gestionar simuladores de iOS y realizar diversas tareas relacionadas con Xcode con un manejo mejorado de errores y soporte para múltiples tipos de proyectos.

Características

Gestión de Proyectos

Establecer proyectos activos y obtener información detallada del proyecto
Crear nuevos proyectos de Xcode a partir de plantillas (iOS, macOS, watchOS, tvOS)
Añadir archivos a proyectos de Xcode con especificación de destino y grupo
Analizar documentos de espacio de trabajo para encontrar proyectos asociados
Listar esquemas disponibles en proyectos y espacios de trabajo

Operaciones con Archivos

Leer/escribir archivos con soporte para diferentes codificaciones
Manejar archivos binarios con codificación/decodificación base64
Buscar contenido de texto dentro de archivos usando patrones y expresiones regulares
Verificar la existencia de archivos y obtener metadatos de archivos
Crear estructuras de directorios automáticamente

Compilación y Pruebas

Compilar proyectos con opciones personalizables
Ejecutar pruebas con informes detallados de fallos
Analizar código para detectar problemas potenciales
Limpiar directorios de compilación
Archivar proyectos para distribución

Integración con CocoaPods

Inicializar CocoaPods en proyectos
Instalar y actualizar pods
Añadir y eliminar dependencias de pods
Ejecutar comandos arbitrarios de pods

Swift Package Manager

Inicializar nuevos paquetes Swift
Añadir y eliminar dependencias de paquetes con varios requisitos de versión
Actualizar paquetes y resolver dependencias
Generar documentación para paquetes Swift usando DocC
Ejecutar pruebas y compilar paquetes Swift

Herramientas de Simulador iOS

Listar simuladores disponibles con información detallada
Iniciar y apagar simuladores
Instalar y lanzar aplicaciones en simuladores
Tomar capturas de pantalla y grabar videos
Gestionar la configuración y el estado del simulador

Utilidades de Xcode

Ejecutar comandos de Xcode mediante xcrun
Compilar catálogos de recursos
Generar conjuntos de iconos de aplicaciones a partir de imágenes fuente
Rastrear el rendimiento de aplicaciones
Exportar y validar archivos para el envío a la App Store
Cambiar entre diferentes versiones de Xcode

Instalación

Requisitos Previos

macOS con Xcode 14.0 o superior instalado
Node.js 16 o superior
npm o yarn
Swift 5.5+ para las funciones de Swift Package Manager
CocoaPods (opcional, para la integración con CocoaPods)

Configuración

Opción 1: Configuración Automatizada (Recomendada)

Utilice el script de configuración incluido que automatiza el proceso de instalación y configuración:

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

Qué Hace el Script de Configuración:

Verificación del Entorno:
- Comprueba que estás ejecutando en macOS
- Verifica que Xcode esté instalado y sea accesible
- Confirma que Node.js (v16+) y npm estén disponibles
- Comprueba la instalación de Ruby
- Verifica la instalación de CocoaPods (ofrece instalarlo si falta)
Instalación de Dependencias:
- Ejecuta npm install para instalar todos los paquetes Node.js requeridos
- Ejecuta npm run build para compilar el código TypeScript
Configuración:
- Crea un archivo .env si no existe
- Solicita tu directorio base de proyectos
- Pregunta si deseas habilitar el registro de depuración
- Guarda tus preferencias de configuración
Integración con Claude Desktop (Opcional):
- Ofrece configurar el servidor para Claude Desktop
- Crea o actualiza el archivo de configuración de Claude Desktop
- Configura el comando y los argumentos adecuados para iniciar el servidor

Cuándo Usar el Script de Configuración:

Instalación por primera vez para asegurar que se cumplan todos los requisitos previos
Cuando deseas una configuración guiada con indicaciones interactivas
Si deseas configurar rápidamente la integración con Claude Desktop
Para verificar que tu entorno tenga todos los componentes necesarios

El script te guiará a través del proceso de configuración con indicaciones claras y comentarios útiles.

Opción 2: Configuración Manual

Cuándo Usar la Configuración Manual:

Prefieres un control explícito sobre cada paso de la instalación
Tienes un entorno personalizado o una configuración no estándar
Estás configurando en un pipeline de CI/CD o entorno automatizado
Deseas personalizar aspectos específicos del proceso de instalación
Eres un desarrollador experimentado familiarizado con proyectos Node.js

Sigue estos pasos para la instalación manual:

Clona el repositorio:

git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

Verifica los requisitos previos (deben estar instalados):
- Xcode y Xcode Command Line Tools
- Node.js v16 o superior
- npm
- Ruby (para soporte de CocoaPods)
- CocoaPods (opcional, para funciones relacionadas con pods)
Instala las dependencias:
```
npm install
```
Compila el proyecto:
```
npm run build
```

Crea un archivo de configuración:

# Option A: Start with the example configuration
cp .env.example .env

# Option B: Create a minimal configuration
echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
echo "DEBUG=false" >> .env

Edita el archivo .env para establecer tu configuración preferida.

Para la integración con Claude Desktop (opcional):
- Edita o crea ~/Library/Application Support/Claude/claude_desktop_config.json
- Añade la siguiente configuración (ajusta las rutas según sea necesario):
```
{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/xcode-mcp-server/dist/index.js"]
    }
  }
}
```

Solución de Problemas de Configuración

Problemas Comunes de Configuración:

Errores de Compilación:
- Asegúrate de tener la versión correcta de Node.js (v16+)
- Intenta eliminar node_modules y ejecutar npm install nuevamente
- Verifica errores de TypeScript con npx tsc --noEmit
- Asegúrate de que todas las importaciones en el código estén resueltas correctamente
Dependencias Faltantes:
- Si ves errores sobre módulos faltantes, ejecuta npm install nuevamente
- Para dependencias nativas, es posible que necesites Xcode Command Line Tools: xcode-select --install
Problemas de Permisos:
- Asegúrate de tener permisos de escritura en el directorio de instalación
- Para la instalación de CocoaPods, es posible que necesites usar sudo gem install cocoapods
Problemas de Configuración:
- Verifica que tu archivo .env tenga el formato correcto y rutas válidas
- Asegúrate de que PROJECTS_BASE_DIR apunte a un directorio existente
- Comprueba que la ruta no contenga caracteres especiales que necesiten escape
Integración con Claude Desktop:
- Asegúrate de que la ruta en la configuración de Claude apunte a la ubicación correcta de index.js
- Reinicia Claude Desktop después de realizar cambios en la configuración
- Verifica que el servidor esté ejecutándose antes de intentar usarlo con Claude

Uso

Iniciar el Servidor

npm start

Para el modo de desarrollo con reinicios automáticos:

npm run dev

Opciones de Configuración

Puedes configurar el servidor de dos maneras:

Variables de entorno en el archivo .env:

PROJECTS_BASE_DIR=/path/to/your/projects
DEBUG=true
ALLOWED_PATHS=/path/to/additional/allowed/directory
PORT=8080

Argumentos de línea de comandos:

npm start -- --projects-dir=/path/to/your/projects --port=8080

Parámetros de Configuración Clave

PROJECTS_BASE_DIR / --projects-dir: Directorio base para proyectos (requerido)
ALLOWED_PATHS / --allowed-paths: Directorios adicionales a los que se permite acceso (separados por comas)
PORT / --port: Puerto para ejecutar el servidor (predeterminado: 3000)
DEBUG / --debug: Habilitar registro de depuración (predeterminado: false)
LOG_LEVEL / --log-level: Establecer nivel de registro (predeterminado: info)

Conexión a Asistentes de IA

El servidor implementa el Protocolo de Contexto del Modelo (MCP), lo que lo hace compatible con varios asistentes de IA que soportan este protocolo. Para conectarse:

Inicia el servidor Xcode MCP
Configura tu asistente de IA para usar la URL del servidor (típicamente http://localhost:3000)
El asistente de IA ahora tendrá acceso a todas las herramientas de Xcode proporcionadas por el servidor

Documentación de Herramientas

Para una visión general completa de todas las herramientas disponibles y su uso, consulta Descripción General de Herramientas.

Para ejemplos de uso detallados y mejores prácticas, consulta Guía del Usuario.

Flujos de Trabajo Comunes

Configuración de un Nuevo Proyecto

// Create a new iOS app project
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// Add a Swift Package dependency
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

Trabajo con Archivos

// Read a file with specific encoding
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// Write to a file
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// Search for text in files
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

Compilación y Pruebas

// Build the project
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// Run tests
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

Estructura del Proyecto

xcode-mcp-server/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── types/                   # Type definitions
│   │   └── index.ts             # Core type definitions
│   ├── utils/                   # Utility functions
│   │   ├── errors.js            # Error handling classes
│   │   ├── pathManager.ts       # Path validation and management
│   │   ├── project.js           # Project utilities
│   │   └── simulator.js         # Simulator utilities
│   └── tools/                   # Tool implementations
│       ├── project/             # Project management tools
│       │   └── index.ts         # Project creation, detection, file adding
│       ├── file/                # File operation tools
│       │   └── index.ts         # File reading, writing, searching
│       ├── build/               # Build and testing tools
│       │   └── index.ts         # Building, testing, analyzing
│       ├── cocoapods/           # CocoaPods integration
│       │   └── index.ts         # Pod installation and management
│       ├── spm/                 # Swift Package Manager tools
│       │   └── index.ts         # Package management and documentation
│       ├── simulator/           # iOS simulator tools
│       │   └── index.ts         # Simulator control and interaction
│       └── xcode/               # Xcode utilities
│           └── index.ts         # Xcode version management, asset tools
├── docs/                        # Documentation
│   ├── tools-overview.md        # Comprehensive tool documentation
│   └── user-guide.md            # Usage examples and best practices
├── tests/                       # Tests
└── dist/                        # Compiled code (generated)

Cómo Funciona

El servidor Xcode MCP utiliza el Protocolo de Contexto del Modelo para proporcionar una interfaz estandarizada para que los modelos de IA interactúen con proyectos de Xcode. La arquitectura del servidor está diseñada con varios componentes clave:

Componentes Principales

Implementación del Servidor: El servidor MCP principal que maneja el registro de herramientas y el procesamiento de solicitudes.
Gestión de Rutas: Asegura el acceso seguro a archivos validando todas las rutas contra los directorios permitidos.
Gestión de Proyectos: Detecta, carga y gestiona diferentes tipos de proyectos de Xcode:
- Proyectos estándar de Xcode (.xcodeproj)
- Espacios de trabajo de Xcode (.xcworkspace)
- Proyectos de Swift Package Manager (Package.swift)
Estado del Directorio: Mantiene el contexto del directorio activo para la resolución de rutas relativas.
Registro de Herramientas: Organiza las herramientas en categorías lógicas para diferentes operaciones de Xcode.

Flujo de Solicitudes

Un asistente de IA envía una solicitud de ejecución de herramienta al servidor MCP.
El servidor valida los parámetros de la solicitud y los permisos.
Se invoca el manejador de herramientas apropiado con los parámetros validados.
La herramienta ejecuta la operación solicitada, a menudo usando comandos nativos de Xcode.
Los resultados se formatean y se devuelven al asistente de IA.
El manejo integral de errores proporciona comentarios significativos para la solución de problemas.

Características de Seguridad

Validación de Rutas: Todas las operaciones de archivos están restringidas a directorios permitidos.
Manejo de Errores: Mensajes de error detallados ayudan a diagnosticar problemas.
Validación de Parámetros: Los parámetros de entrada se validan usando esquemas Zod.
Gestión de Procesos: Los procesos externos se ejecutan de manera segura con un manejo adecuado de errores.

Soporte de Tipos de Proyecto

El servidor maneja inteligentemente diferentes tipos de proyectos:

Proyectos Estándar: Manipulación directa de .xcodeproj
Espacios de Trabajo: Gestiona múltiples proyectos dentro de un espacio de trabajo
Proyectos SPM: Maneja operaciones específicas de Swift Package Manager

Esta arquitectura permite a los asistentes de IA trabajar sin problemas con cualquier tipo de proyecto de Xcode mientras mantiene la seguridad y proporciona comentarios detallados.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción.

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add some amazing feature')
Empuja a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción

Pautas de Desarrollo

Sigue el estilo y la organización del código existente
Añade un manejo integral de errores con mensajes de error específicos
Escribe pruebas para la nueva funcionalidad
Actualiza la documentación para reflejar tus cambios
Asegura la compatibilidad con diferentes tipos de proyectos (estándar, espacio de trabajo, SPM)

Añadir Nuevas Herramientas

Para añadir una nueva herramienta al servidor:

Identifica la categoría apropiada en el directorio src/tools/
Implementa la herramienta usando los patrones existentes con validación de esquema Zod
Registra la herramienta en el archivo index.ts de la categoría
Añade manejo de errores con mensajes de error específicos
Documenta la herramienta en los archivos de documentación apropiados

Solución de Problemas

Problemas Comunes

Errores de Acceso a Rutas: Asegúrate de que las rutas a las que intentas acceder estén dentro de los directorios permitidos
Fallos de Compilación: Verifica que las herramientas de línea de comandos de Xcode estén instaladas y actualizadas
Herramienta No Encontrada: Verifica que el nombre de la herramienta sea correcto y esté registrado adecuadamente
Errores de Validación de Parámetros: Verifica los tipos y requisitos de parámetros en la documentación de la herramienta

Depuración

Inicia el servidor con el registro de depuración habilitado: npm start -- --debug
Verifica la salida de la consola para mensajes de error detallados
Examina los registros del servidor para obtener detalles de solicitudes y respuestas
Para problemas específicos de herramientas, intenta ejecutar el comando equivalente de Xcode directamente en la terminal

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

Gracias al equipo del Protocolo de Contexto del Modelo por el SDK de MCP
Construido con TypeScript y Node.js
Utiliza herramientas de línea de comandos de Xcode y Swift Package Manager
Agradecimiento especial a todos los contribuyentes que han ayudado a mejorar la funcionalidad y robustez del servidor