Xcode

Ferramentas para gerenciamento de projetos Xcode, construção, teste, arquivamento, assinatura de código e utilitários de desenvolvimento iOS

GitHub

Experimente este MCPPatrocinado

Documentação

xcode-mcp

Um servidor MCP (Model Context Protocol) que fornece ferramentas para operações relacionadas ao Xcode, facilitando o trabalho com projetos Xcode a partir de clientes MCP como o Claude Desktop. O servidor oferece diversos utilitários para gerenciamento de projetos Xcode, build, testes, arquivamento, assinatura de código e ferramentas relacionadas ao desenvolvimento iOS.

Recursos

Recuperação de informações do projeto Xcode e listagem de schemes
Capacidades aprimoradas de build com opções de limpeza e saída personalizada
Execução abrangente de testes com controle granular
Arquivamento de aplicativos e exportação IPA para distribuição
Gerenciamento de assinatura de código e perfis de provisionamento
Integração com Swift Package Manager
Gerenciamento do Simulador iOS via simctl
NOVO: Implantação e execução de aplicativos em dispositivos reais com detecção automática de instalação do Xcode e gerenciamento aprimorado de dispositivos
Tratamento inteligente de falhas de instalação de aplicativos com nova tentativa automática
Cache inteligente de informações de dispositivos e Xcode para melhor desempenho

Instalação

npm install @devyhan/xcode-mcp

Uso

Usando com Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Adicione ou modifique a seguinte configuração:

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "npx",
      "args": [
        "@devyhan/xcode-mcp",
        "-y"
      ]
    }
  }
}

Reinicie o Claude Desktop.

Ferramentas Disponíveis

1. xcode-project-info

Recupera informações detalhadas sobre um projeto ou workspace Xcode, incluindo targets, configurações e schemes.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj

Exemplo de Saída:

{
  "project": {
    "name": "MyApp",
    "targets": ["MyApp", "MyAppTests", "MyAppUITests"],
    "configurations": ["Debug", "Release"],
    "schemes": ["MyApp"]
  }
}

2. xcode-list-schemes

Fornece uma lista abrangente de todos os schemes, targets e configurações disponíveis em um projeto ou workspace Xcode.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj

Exemplo de Saída:

Information about project "MyApp":
    Targets:
        MyApp
        MyAppTests
        MyAppUITests

    Build Configurations:
        Debug
        Release

    Schemes:
        MyApp
        MyAppTests

3. xcode-build

Compila um projeto ou workspace Xcode com opções aprimoradas. Suporta builds de workspace e projeto, builds limpos e diretórios de saída personalizados.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)
scheme (obrigatório): O scheme a ser compilado
configuration (opcional): Configuração de build (ex.: Debug, Release)
destination (opcional): Destino do build (ex.: 'platform=iOS Simulator,name=iPhone 14')
extraArgs (opcional): Argumentos adicionais do xcodebuild como array de strings
outputDir (opcional): Diretório de saída personalizado do build (SYMROOT)
clean (opcional): Se deve realizar build limpo (padrão: false)

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Configuration: Debug
Destination: platform=iOS Simulator,name=iPhone 14
Clean: true
OutputDir: /Users/username/Desktop/build

Comando Gerado:

xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" clean build -configuration "Debug" -destination "platform=iOS Simulator,name=iPhone 14" SYMROOT="/Users/username/Desktop/build"

4. xcode-test

Executa testes para um projeto ou workspace Xcode com opções extensas. Fornece controle refinado sobre a execução de testes, incluindo execução de testes específicos, planos de teste e vários modos de teste.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)
scheme (obrigatório): O scheme a ser testado
destination (obrigatório): Destino do teste (ex.: 'platform=iOS Simulator,name=iPhone 14')
testPlan (opcional): Nome do plano de teste a ser usado
onlyTesting (opcional): Array de identificadores de teste específicos para executar
skipTesting (opcional): Array de identificadores de teste para pular
resultBundlePath (opcional): Caminho para salvar o pacote de resultados de teste
buildForTesting (opcional): Compilar apenas para teste sem executar os testes
testWithoutBuilding (opcional): Executar testes sem compilar

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Destination: platform=iOS Simulator,name=iPhone 14
OnlyTesting: ["MyAppTests/LoginTests"]
ResultBundlePath: /Users/username/Desktop/TestResults

Comando Gerado:

xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" -destination "platform=iOS Simulator,name=iPhone 14" test -only-testing:"MyAppTests/LoginTests" -resultBundlePath "/Users/username/Desktop/TestResults"

5. xcode-archive

Cria um arquivo (.xcarchive) de um projeto Xcode e opcionalmente o exporta para um arquivo IPA para distribuição. Suporta métodos de distribuição App Store, ad-hoc e enterprise através do arquivo de opções de exportação.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)
scheme (obrigatório): O scheme a ser arquivado
configuration (opcional): Configuração de build (ex.: Release)
archivePath (obrigatório): Caminho para salvar o arquivo .xcarchive
exportPath (opcional): Caminho para exportar o arquivo (ex.: arquivo IPA)
exportOptionsPlist (opcional): Caminho para o arquivo exportOptions.plist

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Configuration: Release
ArchivePath: /Users/username/Desktop/MyApp.xcarchive
ExportPath: /Users/username/Desktop/Export
ExportOptionsPlist: /Users/username/Projects/MyApp/exportOptions.plist

Comandos Gerados:

# Archive command
xcodebuild -project "/Users/username/Projects/MyApp/MyApp.xcodeproj" -scheme "MyAppScheme" -configuration "Release" archive -archivePath "/Users/username/Desktop/MyApp.xcarchive"

# Export command (if exportPath and exportOptionsPlist are provided)
xcodebuild -exportArchive -archivePath "/Users/username/Desktop/MyApp.xcarchive" -exportPath "/Users/username/Desktop/Export" -exportOptionsPlist "/Users/username/Projects/MyApp/exportOptions.plist"

6. xcode-codesign-info

Recupera informações abrangentes de assinatura de código e perfis de provisionamento para um projeto Xcode. Mostra identidades de assinatura de código instaladas, configurações de assinatura de código do projeto e perfis de provisionamento no sistema.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)
target (opcional): Nome específico do target

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Target: MyAppTarget

Exemplo de Saída:

코드 서명 인증서 목록:
  1) 01AB2345CD6789EF0123456789ABCDEF01234567 "Apple Development: John Doe (ABC12DEF34)"
  2) 9876543210FEDCBA98765432109876543210FEDC "Apple Distribution: Example Corp (XYZ12ABC3)"

프로젝트 코드 서명 설정:
    CODE_SIGN_IDENTITY = Apple Development
    CODE_SIGN_STYLE = Automatic
    DEVELOPMENT_TEAM = ABC123DEF4
    PROVISIONING_PROFILE_SPECIFIER = 

설치된 프로비저닝 프로파일:
-rw-r--r--  1 username  staff  12345 Feb  1 12:34 01234567-89ab-cdef-0123-456789abcdef.mobileprovision
-rw-r--r--  1 username  staff  23456 Mar 15 09:12 fedcba98-7654-3210-fedc-ba9876543210.mobileprovision

7. swift-package-manager

Fornece acesso à funcionalidade do Swift Package Manager (SPM) para gerenciar pacotes Swift. Suporta comandos SPM comuns como init, update, resolve, reset e clean.

Parâmetros:

command (obrigatório): Comando SPM a ser executado ("init", "update", "resolve", "reset", "clean")
packageDir (obrigatório): Caminho do diretório do Swift Package
extraArgs (opcional): Argumentos adicionais do SPM como array de strings

Exemplo:

Command: update
PackageDir: /Users/username/Projects/MySwiftPackage
ExtraArgs: ["--enable-pubgrub-resolver"]

Comando Gerado:

cd "/Users/username/Projects/MySwiftPackage" && swift package update --enable-pubgrub-resolver

Exemplo de Saída:

Resolving dependencies...
Fetching https://github.com/example/example-package.git
Checking out https://github.com/example/example-package.git at 1.2.3

8. simctl-manager

Fornece acesso às capacidades de gerenciamento do Simulador iOS através da ferramenta de linha de comando simctl. Suporta listagem, criação, inicialização, instalação de aplicativos e gerenciamento de dispositivos simulados.

Parâmetros:

command (obrigatório): Comando SimCtl ("list", "create", "boot", "shutdown", "erase", "install", "launch", "delete")
extraArgs (opcional): Argumentos adicionais do simctl como array de strings

Exemplo:

Command: list
ExtraArgs: ["devices", "--json"]

Comando Gerado:

xcrun simctl list devices --json

Exemplo de Saída (abreviado):

{
  "devices": {
    "com.apple.CoreSimulator.SimRuntime.iOS-17-0": [
      {
        "name": "iPhone 14",
        "udid": "12345678-1234-1234-1234-123456789ABC",
        "state": "Booted",
        "isAvailable": true
      }
    ]
  }
}

9. run-on-device

Compila, instala e executa um aplicativo em um dispositivo iOS físico. Suporta nome do dispositivo (incluindo nomes em coreano) ou UUID para seleção do dispositivo, variáveis de ambiente e streaming de logs. Agora com especificação direta de bundleId, opção de pular build e argumentos adicionais de inicialização.

Parâmetros:

projectPath (obrigatório): Caminho para o projeto Xcode (.xcodeproj) ou workspace (.xcworkspace)
scheme (obrigatório): O scheme a ser compilado e executado
device (obrigatório): Identificador ou nome do dispositivo (suporta nomes em coreano)
configuration (opcional): Configuração de build (ex.: Debug, Release)
streamLogs (opcional): Se deve transmitir logs do dispositivo após a inicialização
startStopped (opcional): Se deve iniciar o aplicativo em estado pausado para anexação do depurador
environmentVars (opcional): Variáveis de ambiente para passar ao aplicativo (formato chave1=valor1,chave2=valor2)
xcodePath (opcional): Caminho do aplicativo Xcode (padrão: "/Applications/Xcode-16.2.0.app")
listDevices (opcional): Exibir todos os dispositivos detectados com seus IDs antes de executar
skipBuild (opcional): Pular a etapa de build e instalação para aplicativos já instalados
extraLaunchArgs (opcional): Argumentos adicionais para passar ao comando de inicialização do devicectl
directBundleId (opcional): Especificar diretamente o bundle ID em vez de extrair do projeto

Exemplo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyAppScheme
Device: "Your-iPhone"
Configuration: Debug
StreamLogs: true
EnvironmentVars: "DEBUG_MODE=1,API_URL=https://test-api.example.com"

Processo:

A ferramenta identifica tanto o UDID do Xcode quanto o UUID do CoreDevice para o dispositivo especificado
Ela usa o UDID do Xcode para compilar e instalar o aplicativo
Ela usa o UUID do CoreDevice para iniciar o aplicativo com devicectl
Ela recupera o identificador do bundle do aplicativo
Se solicitado, ela transmite os logs do dispositivo

Principais Melhorias na v0.4.0:

Capacidade de especificar bundleId diretamente sem precisar de um projeto
Pular etapa de build e instalação para aplicativos já instalados
Suporte para argumentos adicionais no comando de inicialização do devicectl
Melhor exibição de informações do modelo do dispositivo e versão do sistema operacional
Melhor tratamento de caminhos e registro de logs para comandos devicectl

Exemplo de Saída:

// Standard output with build and install
앱 실행 결과:
Launched application with com.example.myapp bundle identifier.
로그 스트리밍이 시작되었습니다. 로그는 터미널에서 확인할 수 있습니다.

// Direct bundle ID usage with skip build
기기 모델: iPhone14,7
기기 OS 버전: 17.0
사용자 지정 번들 ID 사용: com.example.myapp
빌드 및 설치 과정 건너뛰기
앱 실행 결과:
Launched application with com.example.myapp bundle identifier.

Cenário de Exemplo: Usando com LLMs

Abaixo está um exemplo de como você pode solicitar a um LLM como o Claude que use essas ferramentas em sequência:

Solicitação do Usuário ao Claude:

I need to inspect my Xcode project, run some tests, and then archive it for distribution.

1. First, use the xcode-list-schemes tool to get all available schemes for my project at /Users/username/Projects/MyApp/MyApp.xcodeproj
2. After you see the schemes, run tests for the first available scheme on the iPhone 14 simulator.
3. Then archive the app for distribution using the Release configuration.

Fluxo de Trabalho Esperado:

O Claude executará a ferramenta xcode-list-schemes para recuperar todos os schemes:
```
Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
```

O Claude executará a ferramenta xcode-test com o scheme identificado:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: [First scheme from output]
Destination: platform=iOS Simulator,name=iPhone 14

O Claude usará então a ferramenta xcode-archive para criar um arquivo:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: [First scheme from output]
Configuration: Release
ArchivePath: /Users/username/Desktop/MyApp.xcarchive

Este fluxo de trabalho demonstra como encadear múltiplas ferramentas, usando a saída de uma ferramenta para informar os parâmetros de outra.

Exemplo: Executando em um Dispositivo Real

Solicitação do Usuário ao Claude:

I need to test my app on a real device:

1. Get the list of available devices (including connected physical devices)
2. Run my app on my connected iPhone

Fluxo de Trabalho Esperado:

O Claude primeiro obterá a lista de dispositivos:
```
listDevices: true
```

O Claude identificará seu dispositivo físico e executará o aplicativo nele:

Project path: /Users/username/Projects/MyApp/MyApp.xcodeproj
Scheme: MyApp
Device: "Your iPhone" (or the device UUID)
StreamLogs: true

Para reinicialização rápida sem recompilar:

Device: "Your iPhone"
DirectBundleId: "com.example.myapp"
SkipBuild: true

Considerações de Segurança

Esta ferramenta pode executar comandos relacionados ao Xcode, o que apresenta riscos de segurança. Observe:

Use apenas com projetos Xcode confiáveis.
Tenha cuidado com projetos de fontes desconhecidas.
Não inclua informações sensíveis nos parâmetros de build.

Desenvolvimento

Requisitos

Node.js 16 ou superior
npm 6 ou superior
Xcode 14 ou superior (para todos os recursos)
Xcode 16 ou superior (necessário para devicectl e recursos de dispositivo real)

Desenvolvimento e Testes Locais

# Clone the repository
git clone https://github.com/devyhan/xcode-mcp.git
cd xcode-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test
npm test

Licença

MIT