XcodeBuildMCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas relacionadas con Xcode para la integración con asistentes de IA y otros clientes MCP.

Tabla de contenido

Descripción general
¿Por qué?
Características
Empezando
Soporte de compilación incremental
Solución de problemas
- Herramienta de diagnóstico
  - Usando con mise
  - Uso con npx
- Registros del servidor MCP
Privacidad
- ¿Qué se envía a Sentry?
- Darse de baja de Sentry
Registro selectivo de herramientas
Población
Contribuyendo
Licencia

Descripción general

Este proyecto implementa un servidor MCP que expone las operaciones de Xcode como herramientas que pueden ser invocadas por agentes de IA mediante el protocolo MCP. Permite la interacción programática con proyectos de Xcode mediante una interfaz estandarizada, optimizada para flujos de trabajo de desarrollo basados en agentes.

¿Por qué?

La herramienta XcodeBuild MCP existe principalmente para optimizar y estandarizar la interacción entre agentes de IA y proyectos Xcode. Al proporcionar herramientas dedicadas a operaciones comunes de Xcode, elimina la dependencia de invocaciones manuales o potencialmente incorrectas de la línea de comandos.

Esto garantiza un proceso de desarrollo confiable y eficiente, permitiendo a los agentes aprovechar sin problemas las capacidades de Xcode y al mismo tiempo reducir el riesgo de errores de configuración.

Fundamentalmente, este MCP permite a los agentes de IA validar de forma independiente los cambios de código mediante la creación de proyectos, la inspección de errores y la iteración autónoma. A diferencia de herramientas controladas por el usuario como Sweetpad, XcodeBuild MCP permite a los agentes automatizar estos flujos de trabajo de forma eficaz.

Características

El servidor XcodeBuildMCP proporciona las siguientes capacidades de herramienta:

Gestión de proyectos de Xcode

Descubrir proyectos : Descubrimiento de proyectos y espacios de trabajo de Xcode
Operaciones de compilación : herramientas de compilación específicas de la plataforma para macOS, simulador de iOS y dispositivos iOS de destino
Información del proyecto : Herramientas para enumerar esquemas y mostrar configuraciones de compilación para proyectos y espacios de trabajo de Xcode
Operaciones de limpieza : limpie productos de compilación utilizando la acción de limpieza nativa de xcodebuild
Compatibilidad con compilaciones incrementales : compilaciones ultrarrápidas que utilizan compatibilidad con compilaciones incrementales (experimental, se requiere suscripción)

Gestión del simulador

Control de simulador : enumera, inicia y abre simuladores de iOS
Implementación de aplicaciones : instalar y ejecutar aplicaciones en simuladores de iOS
Captura de registros : captura registros de tiempo de ejecución desde un simulador
Automatización de la interfaz de usuario : Interactúe con los elementos de la interfaz de usuario del simulador (beta)
Captura de pantalla : captura capturas de pantalla de un simulador (beta)

Utilidades de la aplicación

Extracción de ID de paquete : extraiga identificadores de paquete de paquetes de aplicaciones de iOS y macOS
Lanzamiento de aplicaciones : inicie aplicaciones creadas tanto en simuladores como en macOS

Empezando

Prerrequisitos

macOS 14.5 o posterior
Xcode 16.x o posterior
puesta en escena

Configuración de una línea con mise

Para instalar mise:

# macOS (Homebrew)
brew install mise

# Other installation methods
# See https://mise.jdx.dev/getting-started.html

Para obtener más información sobre mise, visita la documentación oficial .

Configurar clientes MCP

Configure su cliente MCP (Windsurf, Cursor, Claude Desktop, etc.) para usar el servidor XcodeBuildMCP modificando la configuración MCP de su aplicación cliente y cambiando el número de versión para que coincida con la versión que desea usar:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ]
    }
  }
}

[!NOTA] Al usar mise, evite usar la etiqueta @latest ya que mise almacenará en caché el paquete y es posible que no se actualice a la última versión automáticamente; en su lugar, prefiera un número de versión explícito.

[!IMPORTANTE] Tenga en cuenta que XcodeBuildMCP solicitará a xcodebuild que omita la validación de macros. Esto es para evitar errores al compilar proyectos que usan macros de Swift.

Un clic para instalar en VS Code

Habilitación de la automatización de la interfaz de usuario (beta)

Para las funciones de automatización de la interfaz de usuario (tocar, deslizar, captura de pantalla, etc.), necesitarás instalar idb_companion de Facebook:

brew tap facebook/fb
brew install idb-companion

El cliente idb también es necesario, pero XcodeBuildMCP intenta instalarlo automáticamente. Si las funciones de automatización de la interfaz de usuario siguen sin estar disponibles, puede instalar el cliente manualmente con el siguiente comando (suponiendo que tenga instalado Python):

pipx install fb-idb==1.1.7

[!IMPORTANTE] Tenga en cuenta que las funciones de automatización de la interfaz de usuario se encuentran actualmente en fase beta, por lo que podrían presentar algunas imperfecciones. Si encuentra algún problema, infórmelo en el sistema de seguimiento de problemas .

[!NOTA] Es posible que la visualización de imágenes en las respuestas de herramientas y su incrustación en el contexto del chat no sea compatible con todos los clientes MCP; actualmente se sabe que Cursor lo admite.

Soporte de compilación incremental

XcodeBuildMCP incluye compatibilidad experimental con compilaciones incrementales. Esta función está deshabilitada por defecto y se puede habilitar configurando la variable de entorno INCREMENTAL_BUILDS_ENABLED como true .

Para habilitar compilaciones incrementales, configure la variable de entorno INCREMENTAL_BUILDS_ENABLED en true :

Ejemplo de configuración de cliente MCP:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

[!IMPORTANTE] Tenga en cuenta que la compatibilidad con compilaciones incrementales es actualmente muy experimental y su experiencia puede variar. Informe cualquier problema que encuentre al sistema de seguimiento de problemas .

Solución de problemas

Si encuentra problemas con XcodeBuildMCP, la herramienta de diagnóstico puede ayudar a identificar el problema al proporcionar información detallada sobre su entorno y dependencias.

Herramienta de diagnóstico

La herramienta de diagnóstico es una utilidad independiente que verifica la configuración del sistema e informa sobre el estado de todas las dependencias requeridas por XcodeBuildMCP. Resulta especialmente útil para informar problemas.

Usando con mise

# Run the diagnostic tool using mise
mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic

Uso con npx

# Run the diagnostic tool using npx
npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

La herramienta de diagnóstico generará información completa sobre:

Sistema y entorno Node.js
Instalación y configuración de Xcode
Dependencias requeridas (xcodebuild, idb, etc.)
Variables de entorno que afectan a XcodeBuildMCP
Estado de disponibilidad de funciones

Al informar problemas en GitHub, incluya el resultado completo de la herramienta de diagnóstico para ayudar con la solución de problemas.

Registros del servidor MCP

Puede ser útil acceder a los mensajes de registro del servidor MCP para identificar cualquier problema. La aplicación cliente captura los registros, por ejemplo, en Cursor:

Cursor:

find ~/Library/Application\ Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

Si su cliente MCP no tiene archivos de registro, puede ejecutar el servidor directamente con la herramienta Inspector de MCP. Consulte Depuración para obtener más información. Una vez ejecutada, la herramienta MCP imprime todos los mensajes de registro en su panel de errores, lo cual puede ser útil para diagnosticar problemas.

Privacidad

Este proyecto utiliza Sentry para la monitorización y el diagnóstico de errores. Sentry nos ayuda a rastrear problemas, fallos y errores inesperados para mejorar la fiabilidad y la estabilidad de XcodeBuildMCP.

¿Qué se envía a Sentry?

De forma predeterminada, solo se envían a Sentry registros de nivel de error e información de diagnóstico.
Los registros de errores pueden incluir detalles como mensajes de error, seguimientos de pila y (en algunos casos) rutas de archivos o nombres de proyectos. Puede revisar las fuentes en este repositorio para ver exactamente qué se registra.

Darse de baja de Sentry

Si no desea enviar registros de errores a Sentry, puede optar por no hacerlo configurando la variable de entorno SENTRY_DISABLED=true .

Ejemplo de configuración de cliente MCP:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

Registro selectivo de herramientas

De forma predeterminada, todas las herramientas están habilitadas, pero para algunos clientes puede ser útil habilitar solo algunas herramientas específicas para reducir la cantidad de contexto que se envía al cliente. Esto se puede lograr configurando variables de entorno específicas en la configuración de MCP de sus clientes.

Una vez habilitadas una o más herramientas o grupos de herramientas, se deshabilitarán todas las demás. Por ejemplo, para habilitar solo las herramientas relacionadas con el simulador, puede establecer la variable de entorno en XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true Esto solo mostrará las herramientas para compilar, ejecutar y depurar en simuladores.

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

Puede encontrar una lista de herramientas disponibles e instrucciones detalladas sobre cómo habilitarlas en el archivo TOOL_OPTIONS.md .

Población

Corrección autónoma de errores de compilación en Cursor

Utilizando las nuevas funciones de automatización de la interfaz de usuario y captura de pantalla

Creación y ejecución de una aplicación iOS en Claude Desktop

https://github.com/archivos-adjuntos-de-usuario/activos/e3c08d75-8be6-4857-b4d0-9350b26ef086

Contribuyendo

¡Agradecemos tus contribuciones! Aquí te explicamos cómo puedes ayudar a mejorar XcodeBuildMCP.

Consulte nuestro documento CONTRIBUYENDO para obtener más información sobre cómo configurar su entorno local y contribuir al proyecto.

Licencia

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

Integrations