xctools

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

Documentação

Servidor MCP XCTools

Um servidor Model Context Protocol (MCP) que fornece acesso estruturado às ferramentas de desenvolvimento Xcode, incluindo xcrun, xcodebuild e xctrace.

Instalação

Método 1: Usando uvx

Pré-requisitos:
- Python 3.13+
- Xcode com Command Line Tools instalado
- uvx: curl -LsSf https://astral.sh/uv/install.sh | sh
Execute diretamente com uvx:
```
uvx xctools-mcp-server
```

Método 2: Instalação de Desenvolvimento Local

Pré-requisitos:
- Python 3.13+
- Xcode com Command Line Tools instalado

Clone e instale:

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

Execute o servidor:
```
xctools-mcp-server
```

Método 3: Compilar a partir do Código Fonte

Compile o wheel:

python -m build --wheel
pip install dist/xctools_mcp_server-0.1.0-py3-none-any.whl

Configuração

Para Claude Desktop

Adicione ao seu ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Ou se estiver usando uvx:

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

Para VS Code com Extensão MCP

Instale a Extensão MCP no marketplace do VS Code
Adicione a configuração do servidor às configurações do seu VS Code (settings.json):

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

Ou se estiver usando uvx:

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

Reinicie o VS Code para carregar o servidor MCP
Use a Paleta de Comandos (Cmd+Shift+P) e pesquise por comandos "MCP" para interagir com as ferramentas de desenvolvimento Xcode

Para Outros Clientes MCP

O servidor executa em stdio, então você pode invocá-lo diretamente:

Com pacote instalado:

xctools-mcp-server

Com uvx:

uvx xctools-mcp-server

Recursos

Acesso completo ao toolchain Xcode através de xcrun
Compilação e testes de projetos com xcodebuild
Análise de desempenho usando xctrace (Instruments)
Gerenciamento de SDKs e destinos
Tratamento abrangente de erros com mensagens detalhadas
Compatibilidade multiplataforma (macOS com Xcode instalado)

Ferramentas Disponíveis

Ferramentas XCRUN

xcrun_find_tool - Encontre o caminho para ferramentas de desenvolvimento (clang, swift, etc.)
xcrun_show_sdk_path - Mostre o caminho para SDKs
xcrun_show_sdk_version - Mostre versões de SDK
xcrun_run_tool - Execute qualquer ferramenta de desenvolvimento via xcrun

Ferramentas XCODEBUILD

xcodebuild_build - Compile projetos ou workspaces Xcode
xcodebuild_test - Execute testes para projetos/workspaces
xcodebuild_archive - Arquive projetos para distribuição
xcodebuild_list - Liste targets, schemes e configurações
xcodebuild_show_sdks - Liste todos os SDKs disponíveis
xcodebuild_show_destinations - Mostre destinos de compilação válidos

Ferramentas XCTRACE (Instruments)

xctrace_record - Grave novos traces do Instruments
xctrace_import - Importe arquivos suportados para o formato de trace
xctrace_export - Exporte dados de arquivos de trace
xctrace_list - Liste dispositivos, templates ou instruments disponíveis
xctrace_symbolicate - Simbolize traces com símbolos de depuração

Exemplos de Uso

Encontrando Ferramentas de Desenvolvimento

# 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"

Compilando Projetos

# 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álise de Desempenho com 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"

Gerenciamento de SDKs e 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"

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

Falhas de comando: Retorna mensagens de erro detalhadas de xcrun, xcodebuild e xctrace
Xcode ausente: Detecta quando o Xcode Command Line Tools não está disponível
Parâmetros inválidos: Valida argumentos de ferramentas e fornece mensagens de erro úteis
Disponibilidade de ferramentas: Verifica ferramentas necessárias antes da execução

Solução de Problemas

Problemas Comuns

"xcrun: error: unable to find utility"
- Certifique-se de que o Xcode Command Line Tools está instalado: xcode-select --install
- Verifique se o Xcode está configurado corretamente: xcode-select -p
"No developer directory found"
- Instale o Xcode pela Mac App Store
- Aceite a licença do Xcode: sudo xcodebuild -license accept
Erros de permissão
- Certifique-se de que o usuário tem as permissões necessárias para acessar as ferramentas Xcode
- Tente executar com as permissões de desenvolvimento macOS adequadas
Erros de ferramenta não encontrada
- Verifique se a ferramenta específica está disponível na sua instalação do Xcode
- Algumas ferramentas podem exigir versões específicas do Xcode ou componentes adicionais

Requisitos

macOS: Obrigatório (as ferramentas de desenvolvimento Xcode são exclusivas do macOS)
Xcode: Xcode Command Line Tools ou instalação completa do Xcode
Python: 3.13 ou superior
Cliente MCP: Claude Desktop, VS Code com extensão MCP, ou qualquer cliente compatível com MCP

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Parâmetros inválidos: Valida parâmetros de entrada antes da execução
Operações de arquivo: Gerencia arquivos temporários para notificações push com segurança

Considerações de Segurança

O servidor expõe apenas operações de leitura e gerenciamento de simulador
Sem acesso ao sistema de arquivos do host além dos caminhos de app especificados
Payloads de notificações push são validados quanto à estrutura
Alterações de permissão de privacidade são explícitas e registradas

Notas de Desenvolvimento

Construído especificamente para fluxos de trabalho de desenvolvimento iOS
Otimizado para tarefas comuns de gerenciamento de simulador
Análise de saída estruturada para respostas JSON
Suporte para operações individuais e em lote
Compatível com recursos de simulador do Xcode 15+