Directrices de uso de Xcode MCP para agentes de IA

name: xcode-mcp-for-pi-agent description: Pautas para el uso eficiente de las herramientas Xcode MCP a través de la CLI mcporter. Esta habilidad debe usarse para comprender cuándo usar las herramientas Xcode MCP frente a las herramientas estándar. Xcode MCP consume muchos tokens - úsalo solo para compilación, pruebas, simulador, vista previa y diagnósticos SourceKit. Nunca lo uses para operaciones de lectura/escritura/grep de archivos. Usa esta habilidad siempre que trabajes con proyectos Xcode, compilaciones iOS/macOS, vistas previas SwiftUI o desarrollo en plataformas Apple. # Pautas de uso de Xcode MCP Las herramientas Xcode MCP se acceden a través de la CLI `mcporter`, que conecta servidores MCP con herramientas estándar de línea de comandos. Esta habilidad define cuándo usar Xcode MCP y cuándo preferir herramientas estándar. ## Configuración Xcode MCP debe configurarse en `~/.mcporter/mcporter.json`: ```json { "mcpServers": { "xcode": { "command": "xcrun", "args": ["mcpbridge"], "env": {} } } } ``` Verifica la conexión: ```bash mcporter list xcode ``` --- ## Llamada a herramientas Todas las herramientas Xcode MCP se llaman a través de mcporter: ```bash # Lista las herramientas disponibles mcporter list xcode # Llama a una herramienta con argumentos clave:valor mcporter call xcode.<tool_name> param1:value1 param2:value2 # Llama con sintaxis de llamada a función mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")' ``` --- ## Referencia completa de herramientas Xcode MCP ### Gestión de ventanas y proyectos | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Lista las ventanas Xcode abiertas (obtén tabIdentifier) | `mcporter call xcode.XcodeListWindows` | Bajo | ### Operaciones de compilación | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Compila el proyecto Xcode | `mcporter call xcode.BuildProject` | Medio | | Obtén el registro de compilación con errores/advertencias | `mcporter call xcode.GetBuildLog` | Medio | | Lista los problemas en el Navegador de problemas | `mcporter call xcode.XcodeListNavigatorIssues` | Bajo | ### Pruebas | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Obtén las pruebas disponibles del plan de pruebas | `mcporter call xcode.GetTestList` | Bajo | | Ejecuta todas las pruebas | `mcporter call xcode.RunAllTests` | Medio | | Ejecuta pruebas específicas (preferido) | `mcporter call xcode.RunSomeTests` | Medio | ### Vista previa y ejecución | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Renderiza una instantánea de vista previa SwiftUI | `mcporter call xcode.RenderPreview` | Medio | | Ejecuta un fragmento de código en el contexto del archivo | `mcporter call xcode.ExecuteSnippet` | Medio | ### Diagnósticos | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Obtén diagnósticos del compilador para un archivo específico | `mcporter call xcode.XcodeRefreshCodeIssuesInFile` | Bajo | | Obtén diagnósticos SourceKit (todos los archivos abiertos) | `mcporter call xcode.getDiagnostics` | Bajo | ### Documentación | Herramienta | Llamada mcporter | Costo de tokens | |------|---------------|------------| | Busca en la documentación para desarrolladores de Apple | `mcporter call xcode.DocumentationSearch` | Bajo | ### Operaciones de archivos (ALTO CONSUMO DE TOKENS - NUNCA USAR) | Herramienta MCP | Usa en su lugar | Por qué | |----------|-------------|-----| | `xcode.XcodeRead` | Herramienta `Read` / `cat` | Alto consumo de tokens | | `xcode.XcodeWrite` | Herramienta `Write` | Alto consumo de tokens | | `xcode.XcodeUpdate` | Herramienta `Edit` | Alto consumo de tokens | | `xcode.XcodeGrep` | `rg` / `grep` | Alto consumo de tokens | | `xcode.XcodeGlob` | `find` / `glob` | Alto consumo de tokens | | `xcode.XcodeLS` | Comando `ls` | Alto consumo de tokens | | `xcode.XcodeRM` | Comando `rm` | Alto consumo de tokens | | `xcode.XcodeMakeDir` | Comando `mkdir` | Alto consumo de tokens | | `xcode.XcodeMV` | Comando `mv` | Alto consumo de tokens | --- ## Flujos de trabajo recomendados ### 1. Flujo de cambio de código y compilación ``` 1. Busca código -> rg "patrón" --type swift 2. Lee archivo -> Herramienta Read / cat 3. Edita archivo -> Herramienta Edit 4. Verifica sintaxis -> mcporter call xcode.getDiagnostics 5. Compila -> mcporter call xcode.BuildProject 6. Verifica errores -> mcporter call xcode.GetBuildLog (si la compilación falla) ``` ### 2. Flujo de escritura y ejecución de pruebas ``` 1. Lee archivo de prueba -> Herramienta Read / cat 2. Escribe/edita prueba -> Herramienta Edit 3. Obtén lista de pruebas -> mcporter call xcode.GetTestList 4. Ejecuta pruebas -> mcporter call xcode.RunSomeTests (pruebas específicas) 5. Verifica resultados -> Revisa la salida de las pruebas ``` ### 3. Flujo de vista previa SwiftUI ``` 1. Edita vista -> Herramienta Edit 2. Renderiza vista previa -> mcporter call xcode.RenderPreview 3. Itera -> Repite según sea necesario ``` ### 4. Flujo de depuración ``` 1. Verifica diagnósticos -> mcporter call xcode.getDiagnostics 2. Compila proyecto -> mcporter call xcode.BuildProject 3. Obtén registro de compilación -> mcporter call xcode.GetBuildLog severity:error 4. Corrige problemas -> Herramienta Edit 5. Recompila -> mcporter call xcode.BuildProject ``` ### 5. Búsqueda de documentación ``` 1. Busca documentación -> mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack" 2. Revisa resultados -> Usa la información en la implementación ``` --- ## Comandos de respaldo (cuando MCP o mcporter no están disponibles) Si Xcode MCP está desconectado, mcporter no está instalado o la conexión falla, usa estos comandos xcodebuild directamente: ### Comandos de compilación ```bash # Compilación de depuración (simulador) - reemplaza <SchemeName> con el esquema de tu proyecto xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Compilación de lanzamiento (dispositivo) xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build # Compilación con espacio de trabajo (para proyectos CocoaPods) xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Compilación con archivo de proyecto xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Lista los esquemas disponibles xcodebuild -list ``` ### Comandos de prueba ```bash # Ejecuta todas las pruebas xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -configuration Debug # Ejecuta una clase de prueba específica xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName> # Ejecuta un método de prueba específico xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName>/<testMethodName> # Ejecuta con cobertura de código xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -configuration Debug -enableCodeCoverage YES # Lista los simuladores disponibles xcrun simctl list devices available ``` ### Compilación limpia ```bash xcodebuild clean -scheme <SchemeName> ``` --- ## Referencia rápida ### USA mcporter + Xcode MCP para: - `xcode.BuildProject` - Compilación - `xcode.GetBuildLog` - Errores de compilación - `xcode.RunSomeTests` - Ejecución de pruebas específicas - `xcode.GetTestList` - Listado de pruebas - `xcode.RenderPreview` - Vistas previas SwiftUI - `xcode.ExecuteSnippet` - Ejecución de código - `xcode.DocumentationSearch` - Documentación de Apple - `xcode.XcodeListWindows` - Obtener tabIdentifier - `xcode.getDiagnostics` - Errores SourceKit ### NUNCA USES Xcode MCP para: - `xcode.XcodeRead` -> Usa la herramienta `Read` / `cat` - `xcode.XcodeWrite` -> Usa la herramienta `Write` - `xcode.XcodeUpdate` -> Usa la herramienta `Edit` - `xcode.XcodeGrep` -> Usa `rg` o `grep` - `xcode.XcodeGlob` -> Usa `find` / `glob` - `xcode.XcodeLS` -> Usa el comando `ls` - Operaciones de archivos -> Usa herramientas estándar --- ## Resumen de eficiencia de tokens | Operación | Mejor opción | Impacto de tokens | |-----------|-------------|--------------| | Verificación rápida de sintaxis | `mcporter call xcode.getDiagnostics` | Bajo | | Compilación completa | `mcporter call xcode.BuildProject` | Medio | | Ejecutar pruebas específicas | `mcporter call xcode.RunSomeTests` | Medio | | Ejecutar todas las pruebas | `mcporter call xcode.RunAllTests` | Alto | | Leer archivo | Herramienta `Read` / `cat` | Bajo | | Editar archivo | Herramienta `Edit` | Bajo | | Buscar código | `rg` / `grep` | Bajo | | Listar archivos | `ls` / `find` | Bajo |