Servidor MCP de Xcode

Un servidor MCP (Protocolo de Contexto de 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 gestión de errores mejorada y compatibilidad con múltiples tipos de proyectos.

Características

Gestión de proyectos

Establezca proyectos activos y obtenga información detallada del proyecto
Crea nuevos proyectos de Xcode a partir de plantillas (iOS, macOS, watchOS, tvOS)
Agregar archivos a proyectos de Xcode con especificación de grupo y destino
Analizar documentos del espacio de trabajo para encontrar proyectos asociados
Lista de 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
Busque contenido de texto dentro de archivos usando patrones y expresiones regulares
Comprobar la existencia del archivo y obtener sus metadatos
Crear estructuras de directorios automáticamente

Construir y probar

Cree proyectos con opciones personalizables
Ejecutar pruebas con informes detallados de fallos
Analizar el código para detectar posibles problemas
Limpiar directorios de compilación
Proyectos de archivo para distribución

Integración de CocoaPods

Inicializar CocoaPods en proyectos
Instalar y actualizar pods
Agregar y eliminar dependencias de pod
Ejecutar comandos pod arbitrarios

Administrador de paquetes Swift

Inicializar nuevos paquetes Swift
Agregar 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 crear paquetes Swift

Herramientas del simulador de iOS

Lista de simuladores disponibles con información detallada
Simuladores de arranque y apagado
Instalar y ejecutar aplicaciones en simuladores
Tomar capturas de pantalla y grabar vídeos
Administrar la configuración y el estado del simulador

Utilidades de Xcode

Ejecutar comandos Xcode a través de xcrun
Compilar catálogos de activos
Generar conjuntos de iconos de aplicaciones a partir de imágenes de origen
Rastrear el rendimiento de la aplicación
Exportar y validar archivos para enviarlos a la App Store
Cambiar entre diferentes versiones de Xcode

Instalación

Prerrequisitos

macOS con Xcode 14.0 o superior instalado
Node.js 16 o superior
npm o hilo
Características de Swift 5.5+ para Swift Package Manager
CocoaPods (opcional, para la integración de 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 se está ejecutando en macOS
- Verifica que Xcode esté instalado y accesible
- Confirma que Node.js (v16+) y npm están disponibles
- Comprobaciones de instalación de Ruby
- Verifica la instalación de CocoaPods (se ofrece instalarlo si falta)
Instalación de dependencia :
- Ejecuta npm install para instalar todos los paquetes Node.js necesarios
- Ejecuta npm run build para compilar el código TypeScript
Configuración de instalación :
- Crea un archivo .env si no existe uno
- Indicaciones para el directorio base de sus proyectos
- Pregunta si desea habilitar el registro de depuración.
- Guarda sus preferencias de configuración
Integración de escritorio de Claude (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 utilizar el script de configuración:

Primera instalación para garantizar que se cumplan todos los requisitos previos
Cuando desee una configuración guiada con indicaciones interactivas
Si desea configurar rápidamente la integración de Claude Desktop
Para verificar que su entorno tenga todos los componentes necesarios

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

Opción 2: Configuración manual

Cuándo utilizar la configuración manual:

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

Siga estos pasos para la instalación manual:

Clonar el repositorio:
git clone https://github.com/r-huijts/xcode-mcp-server.git cd xcode-mcp-server
Verificar prerrequisitos (deben estar instalados):
- Xcode y herramientas de línea de comandos de Xcode
- Node.js v16 o superior
- npm
- Ruby (para compatibilidad con CocoaPods)
- CocoaPods (opcional, para funciones relacionadas con los pods)
Instalar dependencias:
npm install
Construir el proyecto:
npm run build
Crear 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
Edite el archivo .env para establecer su configuración preferida.
Para la integración de Claude Desktop (opcional):
- Editar o crear ~/Library/Application Support/Claude/claude_desktop_config.json
- Agregue la siguiente configuración (ajuste las rutas según sea necesario): GXP6

Solución de problemas de configuración

Problemas comunes de configuración:

Errores de compilación :
- Asegúrese de tener la versión correcta de Node.js (v16+)
- Intente eliminar node_modules y ejecutar npm install nuevamente
- Compruebe si hay errores de TypeScript con npx tsc --noEmit
- Asegúrese de que todas las importaciones en el código se resuelvan correctamente
Dependencias faltantes :
- Si ve errores sobre módulos faltantes, ejecute npm install nuevamente
- Para las dependencias nativas, es posible que necesite herramientas de línea de comandos de Xcode: xcode-select --install
Problemas de permisos :
- Asegúrese de tener permisos de escritura en el directorio de instalación
- Para instalar CocoaPods, es posible que necesites usar sudo gem install cocoapods
Problemas de configuración :
- Verifique que su archivo .env tenga el formato correcto y rutas válidas
- Asegúrese de que PROJECTS_BASE_DIR apunte a un directorio existente
- Compruebe que la ruta no contenga caracteres especiales que deban escaparse.
Integración de escritorio de Claude :
- Asegúrese de que la ruta en la configuración de Claude apunte a la ubicación correcta de index.js
- Reinicie Claude Desktop después de realizar cambios de configuración
- Compruebe que el servidor esté en funcionamiento antes de intentar usarlo con Claude

Uso

Iniciando el servidor

npm start

Para el modo de desarrollo con reinicios automáticos:

npm run dev

Opciones de configuración

Puede 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 la 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 (obligatorio)
ALLOWED_PATHS / --allowed-paths : Directorios adicionales a los que se permitirá el acceso (separados por comas)
PORT / --port : Puerto donde se ejecutará el servidor (predeterminado: 3000)
DEBUG / --debug : Habilitar el registro de depuración (predeterminado: falso)
LOG_LEVEL / --log-level : Establecer el nivel de registro (predeterminado: información)

Conexión con asistentes de IA

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

Iniciar el servidor MCP de Xcode
Configure su asistente de IA para utilizar la URL del servidor (normalmente http://localhost:3000 )
El asistente de IA ahora tendrá acceso a todas las herramientas Xcode proporcionadas por el servidor

Documentación de herramientas

Para obtener una descripción general completa de todas las herramientas disponibles y su uso, consulte Descripción general de herramientas .

Para obtener ejemplos de uso detallados y mejores prácticas, consulte la Guía del usuario .

Flujos de trabajo comunes

Configurar 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"
});

Trabajar 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
});

Construcció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 MCP de Xcode utiliza el Protocolo de Contexto de Modelo para proporcionar una interfaz estandarizada que permite a los modelos de IA interactuar con los 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 : garantiza el acceso seguro a los archivos validando todas las rutas contra los directorios permitidos.
Gestión de proyectos : detecta, carga y administra diferentes tipos de proyectos Xcode:
- Proyectos estándar de Xcode (.xcodeproj)
- Espacios de trabajo de Xcode (.xcworkspace)
- Proyectos del administrador de paquetes Swift (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 solicitud

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

Características de seguridad

Validación de ruta : todas las operaciones con archivos están restringidas a los directorios permitidos.
Manejo de errores : los mensajes de error detallados ayudan a diagnosticar problemas.
Validación de parámetros : los parámetros de entrada se validan mediante esquemas Zod.
Gestión de procesos : Los procesos externos se ejecutan de forma segura con un manejo adecuado de errores.

Soporte de tipo de proyecto

El servidor gestiona de forma inteligente diferentes tipos de proyectos:

Proyectos estándar : manipulación directa de .xcodeproj
Espacios de trabajo : administra múltiples proyectos dentro de un espacio de trabajo
Proyectos SPM : maneja operaciones específicas del Administrador de paquetes Swift

Esta arquitectura permite que los asistentes de IA trabajen sin problemas con cualquier tipo de proyecto Xcode manteniendo la seguridad y brindando comentarios detallados.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Directrices de desarrollo

Seguir el estilo y la organización del código existente
Agregue un manejo integral de errores con mensajes de error específicos
Escribir pruebas para nuevas funcionalidades
Actualice la documentación para reflejar sus cambios
Garantizar la compatibilidad con diferentes tipos de proyectos (estándar, espacio de trabajo, SPM)

Agregar nuevas herramientas

Para agregar una nueva herramienta al servidor:

Identifique la categoría apropiada en el directorio src/tools/
Implementar la herramienta utilizando los patrones existentes con la validación del esquema Zod
Registrar la herramienta en el archivo index.ts de la categoría
Añadir gestión de errores con mensajes de error específicos
Documentar la herramienta en los archivos de documentación apropiados

Solución de problemas

Problemas comunes

Errores de acceso a rutas : asegúrese de que las rutas a las que intenta acceder estén dentro de los directorios permitidos
Errores de compilación : Verifique que las herramientas de línea de comandos de Xcode estén instaladas y actualizadas
Herramienta no encontrada : Verifique que el nombre de la herramienta sea correcto y esté registrado correctamente
Errores de validación de parámetros : Verifique los tipos de parámetros y los requisitos en la documentación de la herramienta

Depuración

Inicie el servidor con el registro de depuración habilitado: npm start -- --debug
Verifique la salida de la consola para ver mensajes de error detallados
Examinar los registros del servidor para obtener detalles de solicitud y respuesta
Para problemas específicos de la herramienta, intente ejecutar el comando Xcode equivalente directamente en la terminal

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

Gracias al equipo de Model Context Protocol por el MCP SDK
Desarrollado con TypeScript y Node.js
Utiliza herramientas de línea de comandos de Xcode y el Administrador de paquetes Swift
Un agradecimiento especial a todos los colaboradores que han ayudado a mejorar la funcionalidad y robustez del servidor.

Integrations