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:

Qué hace el script de configuración:

1. 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)

2. 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

3. 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

4. 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:

1. Clonar el repositorio:

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

2. 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)

3. Instalar dependencias:

   npm install

4. Construir el proyecto:

   npm run build

5. 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.

6. 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:

1. 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

2. 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

3. 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

4. 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.

5. 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

Para el modo de desarrollo con reinicios automáticos:

Opciones de configuración

Puede configurar el servidor de dos maneras:

1. 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

2. 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:

1. Iniciar el servidor MCP de Xcode

2. Configure su asistente de IA para utilizar la URL del servidor (normalmente http://localhost:3000 )

3. 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

Trabajar con archivos

Construcción y pruebas

Estructura del proyecto

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

1. Implementación del servidor : El servidor MCP principal que maneja el registro de herramientas y el procesamiento de solicitudes.

2. Gestión de rutas : garantiza el acceso seguro a los archivos validando todas las rutas contra los directorios permitidos.

3. 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)

4. Estado del directorio : mantiene el contexto del directorio activo para la resolución de rutas relativas.

5. Registro de herramientas : organiza las herramientas en categorías lógicas para diferentes operaciones de Xcode.

Flujo de solicitud

1. Un asistente de IA envía una solicitud de ejecución de herramienta al servidor MCP.

2. El servidor valida los parámetros y permisos de la solicitud.

3. Se invoca el controlador de herramientas apropiado con los parámetros validados.

4. La herramienta ejecuta la operación solicitada, generalmente utilizando comandos nativos de Xcode.

5. Los resultados se formatean y se devuelven al asistente de IA.

6. 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.

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. 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:

1. Identifique la categoría apropiada en el directorio src/tools/

2. Implementar la herramienta utilizando los patrones existentes con la validación del esquema Zod

3. Registrar la herramienta en el archivo index.ts de la categoría

4. Añadir gestión de errores con mensajes de error específicos

5. 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

1. Inicie el servidor con el registro de depuración habilitado: npm start -- --debug

2. Verifique la salida de la consola para ver mensajes de error detallados

3. Examinar los registros del servidor para obtener detalles de solicitud y respuesta

4. 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.