xctools

🍎 Servidor MCP para xctrace, xcrun, xcodebuild de Xcode.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor MCP de XCTools

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso estructurado a las herramientas de desarrollo de Xcode, incluyendo xcrun, xcodebuild y xctrace.

Instalación

Método 1: Usando uvx

  1. Requisitos previos:

    • Python 3.13+
    • Xcode con herramientas de línea de comandos instaladas
    • uvx: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Ejecutar directamente con uvx:

    uvx xctools-mcp-server

Método 2: Instalación de desarrollo local

  1. Requisitos previos:

    • Python 3.13+
    • Xcode con herramientas de línea de comandos instaladas

  2. Clonar e instalar:

    git clone https://github.com/nzrsky/xctools-mcp-server
cd xctools-mcp-server
pip install .

  3. Ejecutar el servidor:

    xctools-mcp-server

Método 3: Compilar desde el código fuente

  1. Compilar el paquete wheel: 
    python -m build --wheel
pip install dist/xctools_mcp_server-0.1.0-py3-none-any.whl

Configuración

Para Claude Desktop

Añadir a su ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xctools": {
      "command": "xctools-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

O si se usa uvx:

{
  "mcpServers": {
    "xctools": {
      "command": "uvx",
      "args": ["xctools-mcp-server"],
      "env": {}
    }
  }
}

Para VS Code con la extensión MCP

  1. Instalar la extensión MCP desde el mercado de VS Code
  2. Añadir la configuración del servidor a la configuración de VS Code (settings.json):
{
  "mcp.servers": {
    "xctools": {
      "command": "xctools-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

O si se usa uvx:

{
  "mcp.servers": {
    "xctools": {
      "command": "uvx",
      "args": ["xctools-mcp-server"],
      "env": {}
    }
  }
}
  1. Reiniciar VS Code para cargar el servidor MCP
  2. Usar la paleta de comandos (Cmd+Shift+P) y buscar comandos "MCP" para interactuar con las herramientas de desarrollo de Xcode

Para otros clientes MCP

El servidor se ejecuta en stdio, por lo que puede invocarse directamente:

Con el paquete instalado:

xctools-mcp-server

Con uvx:

uvx xctools-mcp-server

Características

  • Acceso completo al conjunto de herramientas de Xcode a través de xcrun
  • Compilación y pruebas de proyectos con xcodebuild
  • Análisis de rendimiento usando xctrace (Instruments)
  • Gestión de SDK y destinos
  • Manejo integral de errores con mensajes detallados
  • Compatibilidad multiplataforma (macOS con Xcode instalado)

Herramientas disponibles

Herramientas XCRUN

  • xcrun_find_tool - Encontrar la ruta a las herramientas de desarrollo (clang, swift, etc.)
  • xcrun_show_sdk_path - Mostrar la ruta a los SDK
  • xcrun_show_sdk_version - Mostrar versiones de SDK
  • xcrun_run_tool - Ejecutar cualquier herramienta de desarrollo mediante xcrun

Herramientas XCODEBUILD

  • xcodebuild_build - Compilar proyectos o espacios de trabajo de Xcode
  • xcodebuild_test - Ejecutar pruebas para proyectos/espacios de trabajo
  • xcodebuild_archive - Archivar proyectos para distribución
  • xcodebuild_list - Listar objetivos, esquemas y configuraciones
  • xcodebuild_show_sdks - Listar todos los SDK disponibles
  • xcodebuild_show_destinations - Mostrar destinos de compilación válidos

Herramientas XCTRACE (Instruments)

  • xctrace_record - Grabar nuevos seguimientos de Instruments
  • xctrace_import - Importar archivos compatibles al formato de seguimiento
  • xctrace_export - Exportar datos de archivos de seguimiento
  • xctrace_list - Listar dispositivos, plantillas o instrumentos disponibles
  • xctrace_symbolicate - Simbolizar seguimientos con símbolos de depuración

Ejemplos de uso

Encontrar herramientas de desarrollo

# Find the path to a specific tool
"Find the path to clang compiler"

# Show SDK path for iOS
"Show the path to the iOS SDK"

# Get SDK version information
"Show the version of the iOS SDK"

Compilar proyectos

# Build an Xcode project
"Build the project MyApp.xcodeproj for iOS simulator"

# Run tests for a workspace
"Run tests for MyApp.xcworkspace on iPhone 15 Pro simulator"

# Archive for distribution
"Archive MyApp.xcworkspace for release"

# List project information
"List all schemes and targets in MyApp.xcodeproj"

Análisis de rendimiento con Instruments

# Record a trace for Time Profiler
"Record a Time Profiler trace for MyApp on iPhone 15 Pro for 30 seconds"

# List available instruments
"List all available Instruments templates"

# Export trace data
"Export data from trace file to XML format"

# Import a file for analysis
"Import a .dtps file into Instruments trace format"

Gestión de SDK y destinos

# List all available SDKs
"Show all available SDKs for building"

# Show build destinations
"List all available destinations for iOS builds"

# Run a tool via xcrun
"Run swift command with version flag via xcrun"

Manejo de errores

El servidor incluye manejo integral de errores:

  • Fallos de comandos: Devuelve mensajes de error detallados de xcrun, xcodebuild y xctrace
  • Xcode faltante: Detecta cuando las herramientas de línea de comandos de Xcode no están disponibles
  • Parámetros no válidos: Valida los argumentos de las herramientas y proporciona mensajes de error útiles
  • Disponibilidad de herramientas: Verifica las herramientas requeridas antes de la ejecución

Solución de problemas

Problemas comunes

  1. "xcrun: error: unable to find utility"

    • Asegúrese de que las herramientas de línea de comandos de Xcode estén instaladas: xcode-select --install
    • Verifique que Xcode esté configurado correctamente: xcode-select -p

  2. "No developer directory found"

    • Instale Xcode desde la Mac App Store
    • Acepte la licencia de Xcode: sudo xcodebuild -license accept

  3. Errores de permisos

    • Asegúrese de que el usuario tenga los permisos necesarios para acceder a las herramientas de Xcode
    • Intente ejecutar con los permisos de desarrollo adecuados de macOS

  4. Errores de herramienta no encontrada

    • Verifique que la herramienta específica esté disponible en su instalación de Xcode
    • Algunas herramientas pueden requerir versiones específicas de Xcode o componentes adicionales

Requisitos

  • macOS: Requerido (las herramientas de desarrollo de Xcode son solo para macOS)
  • Xcode: Herramientas de línea de comandos de Xcode o instalación completa de Xcode
  • Python: 3.13 o superior
  • Cliente MCP: Claude Desktop, VS Code con extensión MCP, o cualquier cliente compatible con MCP

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de Extracción (Pull Request).

Licencia

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

  • Parámetros no válidos: Valida los parámetros de entrada antes de la ejecución
  • Operaciones de archivos: Maneja archivos temporales para notificaciones push de forma segura

Consideraciones de seguridad

  • El servidor solo expone operaciones de lectura y gestión del simulador
  • Sin acceso al sistema de archivos del host más allá de las rutas de aplicaciones especificadas
  • Las cargas útiles de notificaciones push se validan en cuanto a su estructura
  • Los cambios de permisos de privacidad son explícitos y se registran

Notas de desarrollo

  • Construido específicamente para flujos de trabajo de desarrollo de iOS
  • Optimizado para tareas comunes de gestión del simulador
  • Análisis de salida estructurada para respuestas JSON
  • Soporte para operaciones individuales y por lotes
  • Compatible con funciones del simulador de Xcode 15+