Diretrizes de Uso do Xcode MCP para Agentes de IA

name: xcode-mcp-for-pi-agent description: Diretrizes para uso eficiente das ferramentas Xcode MCP via CLI mcporter. Esta skill deve ser usada para entender quando usar as ferramentas Xcode MCP versus ferramentas padrão. Xcode MCP consome muitos tokens - use apenas para build, teste, simulador, preview e diagnósticos SourceKit. Nunca use para operações de leitura/escrita/grep de arquivos. Use esta skill sempre que trabalhar com projetos Xcode, builds iOS/macOS, previews SwiftUI ou desenvolvimento para plataformas Apple. # Diretrizes de Uso do Xcode MCP As ferramentas Xcode MCP são acessadas via CLI `mcporter`, que faz a ponte entre servidores MCP e ferramentas de linha de comando padrão. Esta skill define quando usar Xcode MCP e quando preferir ferramentas padrão. ## Configuração O Xcode MCP deve ser configurado em `~/.mcporter/mcporter.json`: ```json { "mcpServers": { "xcode": { "command": "xcrun", "args": ["mcpbridge"], "env": {} } } } ``` Verifique a conexão: ```bash mcporter list xcode ``` --- ## Chamando Ferramentas Todas as ferramentas Xcode MCP são chamadas via mcporter: ```bash # Listar ferramentas disponíveis mcporter list xcode # Chamar uma ferramenta com argumentos chave:valor mcporter call xcode.<nome_da_ferramenta> param1:valor1 param2:valor2 # Chamar com sintaxe de chamada de função mcporter call 'xcode.<nome_da_ferramenta>(param1: "valor1", param2: "valor2")' ``` --- ## Referência Completa das Ferramentas Xcode MCP ### Gerenciamento de Janelas e Projetos | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Listar janelas Xcode abertas (obter tabIdentifier) | `mcporter call xcode.XcodeListWindows` | Baixo | ### Operações de Build | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Build do projeto Xcode | `mcporter call xcode.BuildProject` | Médio | | Obter log de build com erros/avisos | `mcporter call xcode.GetBuildLog` | Médio | | Listar problemas no Issue Navigator | `mcporter call xcode.XcodeListNavigatorIssues` | Baixo | ### Testes | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Obter testes disponíveis do plano de teste | `mcporter call xcode.GetTestList` | Baixo | | Executar todos os testes | `mcporter call xcode.RunAllTests` | Médio | | Executar testes específicos (preferido) | `mcporter call xcode.RunSomeTests` | Médio | ### Preview e Execução | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Renderizar snapshot do SwiftUI Preview | `mcporter call xcode.RenderPreview` | Médio | | Executar trecho de código no contexto do arquivo | `mcporter call xcode.ExecuteSnippet` | Médio | ### Diagnósticos | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Obter diagnósticos do compilador para arquivo específico | `mcporter call xcode.XcodeRefreshCodeIssuesInFile` | Baixo | | Obter diagnósticos SourceKit (todos os arquivos abertos) | `mcporter call xcode.getDiagnostics` | Baixo | ### Documentação | Ferramenta | Chamada mcporter | Custo de Tokens | |------|---------------|------------| | Pesquisar Documentação do Apple Developer | `mcporter call xcode.DocumentationSearch` | Baixo | ### Operações de Arquivo (ALTO TOKEN - NUNCA USE) | Ferramenta MCP | Use em vez disso | Por quê | |----------|-------------|-----| | `xcode.XcodeRead` | Ferramenta `Read` / `cat` | Alto consumo de tokens | | `xcode.XcodeWrite` | Ferramenta `Write` | Alto consumo de tokens | | `xcode.XcodeUpdate` | Ferramenta `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 | --- ## Fluxos de Trabalho Recomendados ### 1. Fluxo de Alteração de Código e Build ``` 1. Pesquisar código -> rg "padrão" --type swift 2. Ler arquivo -> Ferramenta Read / cat 3. Editar arquivo -> Ferramenta Edit 4. Verificação de sintaxe -> mcporter call xcode.getDiagnostics 5. Build -> mcporter call xcode.BuildProject 6. Verificar erros -> mcporter call xcode.GetBuildLog (se o build falhar) ``` ### 2. Fluxo de Escrita e Execução de Testes ``` 1. Ler arquivo de teste -> Ferramenta Read / cat 2. Escrever/editar teste -> Ferramenta Edit 3. Obter lista de testes -> mcporter call xcode.GetTestList 4. Executar testes -> mcporter call xcode.RunSomeTests (testes específicos) 5. Verificar resultados -> Revisar saída do teste ``` ### 3. Fluxo de Preview SwiftUI ``` 1. Editar view -> Ferramenta Edit 2. Renderizar preview -> mcporter call xcode.RenderPreview 3. Iterar -> Repetir conforme necessário ``` ### 4. Fluxo de Depuração ``` 1. Verificar diagnósticos -> mcporter call xcode.getDiagnostics 2. Build do projeto -> mcporter call xcode.BuildProject 3. Obter log de build -> mcporter call xcode.GetBuildLog severity:error 4. Corrigir problemas -> Ferramenta Edit 5. Rebuild -> mcporter call xcode.BuildProject ``` ### 5. Pesquisa de Documentação ``` 1. Pesquisar docs -> mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack" 2. Revisar resultados -> Usar informações na implementação ``` --- ## Comandos de Fallback (Quando MCP ou mcporter Indisponíveis) Se o Xcode MCP estiver desconectado, o mcporter não estiver instalado ou a conexão falhar, use estes comandos xcodebuild diretamente: ### Comandos de Build ```bash # Build de depuração (simulador) - substitua <SchemeName> pelo scheme do seu projeto xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Build de release (dispositivo) xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build # Build com workspace (para projetos CocoaPods) xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Build com arquivo de projeto xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # Listar schemes disponíveis xcodebuild -list ``` ### Comandos de Teste ```bash # Executar todos os testes xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -configuration Debug # Executar classe de teste específica xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName> # Executar método de teste específico xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName>/<testMethodName> # Executar com cobertura de código xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -configuration Debug -enableCodeCoverage YES # Listar simuladores disponíveis xcrun simctl list devices available ``` ### Build Limpo ```bash xcodebuild clean -scheme <SchemeName> ``` --- ## Referência Rápida ### USE mcporter + Xcode MCP Para: - `xcode.BuildProject` - Build - `xcode.GetBuildLog` - Erros de build - `xcode.RunSomeTests` - Executar testes específicos - `xcode.GetTestList` - Listar testes - `xcode.RenderPreview` - Previews SwiftUI - `xcode.ExecuteSnippet` - Execução de código - `xcode.DocumentationSearch` - Documentação Apple - `xcode.XcodeListWindows` - Obter tabIdentifier - `xcode.getDiagnostics` - Erros SourceKit ### NUNCA USE Xcode MCP Para: - `xcode.XcodeRead` -> Use ferramenta `Read` / `cat` - `xcode.XcodeWrite` -> Use ferramenta `Write` - `xcode.XcodeUpdate` -> Use ferramenta `Edit` - `xcode.XcodeGrep` -> Use `rg` ou `grep` - `xcode.XcodeGlob` -> Use `find` / `glob` - `xcode.XcodeLS` -> Use comando `ls` - Operações de arquivo -> Use ferramentas padrão --- ## Resumo de Eficiência de Tokens | Operação | Melhor Escolha | Impacto de Tokens | |-----------|-------------|--------------| | Verificação rápida de sintaxe | `mcporter call xcode.getDiagnostics` | Baixo | | Build completo | `mcporter call xcode.BuildProject` | Médio | | Executar testes específicos | `mcporter call xcode.RunSomeTests` | Médio | | Executar todos os testes | `mcporter call xcode.RunAllTests` | Alto | | Ler arquivo | Ferramenta `Read` / `cat` | Baixo | | Editar arquivo | Ferramenta `Edit` | Baixo | | Pesquisar código | `rg` / `grep` | Baixo | | Listar arquivos | `ls` / `find` | Baixo |