Xcode MCP

Integre-se com o Xcode para construir e gerenciar seus projetos.

Documentação

Servidor Xcode MCP

Um servidor MCP (Model Context Protocol) que fornece integração abrangente com o Xcode para assistentes de IA. Este servidor permite que agentes de IA interajam com projetos Xcode, gerenciem simuladores iOS e executem diversas tarefas relacionadas ao Xcode com tratamento aprimorado de erros e suporte para múltiplos tipos de projeto.

Recursos

Gerenciamento de Projetos

Definir projetos ativos e obter informações detalhadas do projeto
Criar novos projetos Xcode a partir de modelos (iOS, macOS, watchOS, tvOS)
Adicionar arquivos a projetos Xcode com especificação de destino e grupo
Analisar documentos de workspace para encontrar projetos associados
Listar esquemas disponíveis em projetos e workspaces

Operações com Arquivos

Ler/escrever arquivos com suporte a diferentes codificações
Lidar com arquivos binários usando codificação/decodificação base64
Pesquisar conteúdo de texto em arquivos usando padrões e regex
Verificar existência de arquivos e obter metadados de arquivos
Criar estruturas de diretórios automaticamente

Build e Testes

Compilar projetos com opções personalizáveis
Executar testes com relatórios detalhados de falhas
Analisar código em busca de problemas potenciais
Limpar diretórios de build
Arquivar projetos para distribuição

Integração com CocoaPods

Inicializar CocoaPods em projetos
Instalar e atualizar pods
Adicionar e remover dependências de pods
Executar comandos arbitrários de pods

Swift Package Manager

Inicializar novos pacotes Swift
Adicionar e remover dependências de pacotes com vários requisitos de versão
Atualizar pacotes e resolver dependências
Gerar documentação para pacotes Swift usando DocC
Executar testes e compilar pacotes Swift

Ferramentas do Simulador iOS

Listar simuladores disponíveis com informações detalhadas
Iniciar e desligar simuladores
Instalar e iniciar aplicativos em simuladores
Tirar capturas de tela e gravar vídeos
Gerenciar configurações e estado do simulador

Utilitários do Xcode

Executar comandos do Xcode via xcrun
Compilar catálogos de assets
Gerar conjuntos de ícones de aplicativos a partir de imagens de origem
Rastrear desempenho de aplicativos
Exportar e validar arquivos para envio à App Store
Alternar entre diferentes versões do Xcode

Instalação

Pré-requisitos

macOS com Xcode 14.0 ou superior instalado
Node.js 16 ou superior
npm ou yarn
Swift 5.5+ para recursos do Swift Package Manager
CocoaPods (opcional, para integração com CocoaPods)

Configuração

Opção 1: Configuração Automatizada (Recomendada)

Use o script de configuração incluído, que automatiza o processo de instalação e configuração:

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

O que o Script de Configuração Faz:

Verificação do Ambiente:
- Verifica se você está executando no macOS
- Confirma que o Xcode está instalado e acessível
- Verifica se Node.js (v16+) e npm estão disponíveis
- Verifica a instalação do Ruby
- Verifica a instalação do CocoaPods (oferece instalar se estiver ausente)
Instalação de Dependências:
- Executa npm install para instalar todos os pacotes Node.js necessários
- Executa npm run build para compilar o código TypeScript
Configuração:
- Cria um arquivo .env se não existir
- Solicita o diretório base dos seus projetos
- Pergunta se você deseja habilitar o registro de depuração
- Salva suas preferências de configuração
Integração com Claude Desktop (Opcional):
- Oferece configurar o servidor para o Claude Desktop
- Cria ou atualiza o arquivo de configuração do Claude Desktop
- Configura o comando e os argumentos adequados para iniciar o servidor

Quando Usar o Script de Configuração:

Instalação pela primeira vez para garantir que todos os pré-requisitos sejam atendidos
Quando você deseja uma configuração guiada com prompts interativos
Se você deseja configurar rapidamente a integração com o Claude Desktop
Para verificar se seu ambiente possui todos os componentes necessários

O script irá guiá-lo pelo processo de configuração com prompts claros e feedback útil.

Opção 2: Configuração Manual

Quando Usar a Configuração Manual:

Você prefere controle explícito sobre cada etapa da instalação
Você tem um ambiente personalizado ou configuração não padrão
Você está configurando em um pipeline de CI/CD ou ambiente automatizado
Você deseja personalizar aspectos específicos do processo de instalação
Você é um desenvolvedor experiente familiarizado com projetos Node.js

Siga estas etapas para instalação manual:

Clone o repositório:

git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

Verifique os pré-requisitos (eles devem estar instalados):
- Xcode e Ferramentas de Linha de Comando do Xcode
- Node.js v16 ou superior
- npm
- Ruby (para suporte ao CocoaPods)
- CocoaPods (opcional, para recursos relacionados a pods)
Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```

Crie um arquivo de configuração:

# Option A: Start with the example configuration
cp .env.example .env

# Option B: Create a minimal configuration
echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
echo "DEBUG=false" >> .env

Edite o arquivo .env para definir sua configuração preferida.

Para integração com Claude Desktop (opcional):
- Edite ou crie ~/Library/Application Support/Claude/claude_desktop_config.json
- Adicione a seguinte configuração (ajuste os caminhos conforme necessário):
```
{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/xcode-mcp-server/dist/index.js"]
    }
  }
}
```

Solução de Problemas na Configuração

Problemas Comuns de Configuração:

Erros de Compilação:
- Certifique-se de ter a versão correta do Node.js (v16+)
- Tente excluir node_modules e executar npm install novamente
- Verifique erros de TypeScript com npx tsc --noEmit
- Certifique-se de que todas as importações no código estejam resolvidas corretamente
Dependências Ausentes:
- Se você vir erros sobre módulos ausentes, execute npm install novamente
- Para dependências nativas, você pode precisar das Ferramentas de Linha de Comando do Xcode: xcode-select --install
Problemas de Permissão:
- Certifique-se de ter permissões de escrita no diretório de instalação
- Para instalação do CocoaPods, você pode precisar usar sudo gem install cocoapods
Problemas de Configuração:
- Verifique se seu arquivo .env tem o formato correto e caminhos válidos
- Certifique-se de que PROJECTS_BASE_DIR aponte para um diretório existente
- Verifique se o caminho não contém caracteres especiais que precisam de escape
Integração com Claude Desktop:
- Certifique-se de que o caminho na configuração do Claude aponte para o local correto de index.js
- Reinicie o Claude Desktop após fazer alterações na configuração
- Verifique se o servidor está em execução antes de tentar usá-lo com o Claude

Uso

Iniciando o Servidor

npm start

Para modo de desenvolvimento com reinicializações automáticas:

npm run dev

Opções de Configuração

Você pode configurar o servidor de duas maneiras:

Variáveis de ambiente no arquivo .env:

PROJECTS_BASE_DIR=/path/to/your/projects
DEBUG=true
ALLOWED_PATHS=/path/to/additional/allowed/directory
PORT=8080

Argumentos de linha de comando:

npm start -- --projects-dir=/path/to/your/projects --port=8080

Parâmetros de Configuração Principais

PROJECTS_BASE_DIR / --projects-dir: Diretório base para projetos (obrigatório)
ALLOWED_PATHS / --allowed-paths: Diretórios adicionais para permitir acesso (separados por vírgula)
PORT / --port: Porta para executar o servidor (padrão: 3000)
DEBUG / --debug: Habilitar registro de depuração (padrão: falso)
LOG_LEVEL / --log-level: Definir nível de registro (padrão: info)

Conectando a Assistentes de IA

O servidor implementa o Model Context Protocol (MCP), tornando-o compatível com vários assistentes de IA que suportam este protocolo. Para conectar:

Inicie o servidor Xcode MCP
Configure seu assistente de IA para usar a URL do servidor (tipicamente http://localhost:3000)
O assistente de IA agora terá acesso a todas as ferramentas Xcode fornecidas pelo servidor

Documentação de Ferramentas

Para uma visão geral abrangente de todas as ferramentas disponíveis e seu uso, consulte Visão Geral das Ferramentas.

Para exemplos detalhados de uso e melhores práticas, consulte Guia do Usuário.

Fluxos de Trabalho Comuns

Configurando um Novo Projeto

// Create a new iOS app project
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// Add a Swift Package dependency
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

Trabalhando com Arquivos

// Read a file with specific encoding
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// Write to a file
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// Search for text in files
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

Compilando e Testando

// Build the project
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// Run tests
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

Estrutura do Projeto

xcode-mcp-server/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── types/                   # Type definitions
│   │   └── index.ts             # Core type definitions
│   ├── utils/                   # Utility functions
│   │   ├── errors.js            # Error handling classes
│   │   ├── pathManager.ts       # Path validation and management
│   │   ├── project.js           # Project utilities
│   │   └── simulator.js         # Simulator utilities
│   └── tools/                   # Tool implementations
│       ├── project/             # Project management tools
│       │   └── index.ts         # Project creation, detection, file adding
│       ├── file/                # File operation tools
│       │   └── index.ts         # File reading, writing, searching
│       ├── build/               # Build and testing tools
│       │   └── index.ts         # Building, testing, analyzing
│       ├── cocoapods/           # CocoaPods integration
│       │   └── index.ts         # Pod installation and management
│       ├── spm/                 # Swift Package Manager tools
│       │   └── index.ts         # Package management and documentation
│       ├── simulator/           # iOS simulator tools
│       │   └── index.ts         # Simulator control and interaction
│       └── xcode/               # Xcode utilities
│           └── index.ts         # Xcode version management, asset tools
├── docs/                        # Documentation
│   ├── tools-overview.md        # Comprehensive tool documentation
│   └── user-guide.md            # Usage examples and best practices
├── tests/                       # Tests
└── dist/                        # Compiled code (generated)

Como Funciona

O servidor Xcode MCP usa o Model Context Protocol para fornecer uma interface padronizada para modelos de IA interagirem com projetos Xcode. A arquitetura do servidor é projetada com vários componentes-chave:

Componentes Principais

Implementação do Servidor: O servidor MCP principal que lida com registro de ferramentas e processamento de solicitações.
Gerenciamento de Caminhos: Garante acesso seguro a arquivos validando todos os caminhos contra diretórios permitidos.
Gerenciamento de Projetos: Detecta, carrega e gerencia diferentes tipos de projetos Xcode:
- Projetos Xcode padrão (.xcodeproj)
- Workspaces Xcode (.xcworkspace)
- Projetos Swift Package Manager (Package.swift)
Estado do Diretório: Mantém o contexto do diretório ativo para resolução de caminhos relativos.
Registro de Ferramentas: Organiza ferramentas em categorias lógicas para diferentes operações do Xcode.

Fluxo de Solicitações

Um assistente de IA envia uma solicitação de execução de ferramenta ao servidor MCP.
O servidor valida os parâmetros e permissões da solicitação.
O manipulador de ferramenta apropriado é invocado com os parâmetros validados.
A ferramenta executa a operação solicitada, frequentemente usando comandos nativos do Xcode.
Os resultados são formatados e retornados ao assistente de IA.
O tratamento abrangente de erros fornece feedback significativo para solução de problemas.

Recursos de Segurança

Validação de Caminhos: Todas as operações de arquivo são restritas a diretórios permitidos.
Tratamento de Erros: Mensagens de erro detalhadas ajudam a diagnosticar problemas.
Validação de Parâmetros: Parâmetros de entrada são validados usando esquemas Zod.
Gerenciamento de Processos: Processos externos são executados com segurança e tratamento adequado de erros.

Suporte a Tipos de Projeto

O servidor lida inteligentemente com diferentes tipos de projeto:

Projetos Padrão: Manipulação direta de .xcodeproj
Workspaces: Gerencia múltiplos projetos dentro de um workspace
Projetos SPM: Lida com operações específicas do Swift Package Manager

Esta arquitetura permite que assistentes de IA trabalhem perfeitamente com qualquer tipo de projeto Xcode, mantendo a segurança e fornecendo feedback detalhado.

Contribuindo

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

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Diretrizes de Desenvolvimento

Siga o estilo e a organização de código existentes
Adicione tratamento abrangente de erros com mensagens de erro específicas
Escreva testes para novas funcionalidades
Atualize a documentação para refletir suas alterações
Garanta compatibilidade com diferentes tipos de projeto (padrão, workspace, SPM)

Adicionando Novas Ferramentas

Para adicionar uma nova ferramenta ao servidor:

Identifique a categoria apropriada no diretório src/tools/
Implemente a ferramenta usando os padrões existentes com validação de esquema Zod
Registre a ferramenta no arquivo index.ts da categoria
Adicione tratamento de erros com mensagens de erro específicas
Documente a ferramenta nos arquivos de documentação apropriados

Solução de Problemas

Problemas Comuns

Erros de Acesso a Caminhos: Certifique-se de que os caminhos que você está tentando acessar estão dentro dos diretórios permitidos
Falhas de Compilação: Verifique se as ferramentas de linha de comando do Xcode estão instaladas e atualizadas
Ferramenta Não Encontrada: Verifique se o nome da ferramenta está correto e devidamente registrado
Erros de Validação de Parâmetros: Verifique os tipos e requisitos de parâmetros na documentação da ferramenta

Depuração

Inicie o servidor com registro de depuração habilitado: npm start -- --debug
Verifique a saída do console para mensagens de erro detalhadas
Examine os logs do servidor para detalhes de solicitações e respostas
Para problemas específicos de ferramentas, tente executar o comando Xcode equivalente diretamente no terminal

Licença

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

Agradecimentos

Agradecimentos à equipe do Model Context Protocol pelo SDK MCP
Construído com TypeScript e Node.js
Usa ferramentas de linha de comando do Xcode e Swift Package Manager
Agradecimentos especiais a todos os contribuidores que ajudaram a melhorar a funcionalidade e robustez do servidor