Xcode MCP Server

AI asistanları için kapsamlı Xcode entegrasyonu sağlayan bir MCP (Model Context Protocol) sunucusu. Bu sunucu, AI ajanlarının Xcode projeleriyle etkileşim kurmasını, iOS simülatörleri yönetmesini ve geliştirilmiş hata işleme ve çoklu proje türleri desteği ile çeşitli Xcode ile ilgili görevleri gerçekleştirmesini sağlar.

Özellikler

Proje Yönetimi

• Aktif projeleri ayarlama ve ayrıntılı proje bilgisi alma
• Şablonlardan yeni Xcode projeleri oluşturma (iOS, macOS, watchOS, tvOS)
• Xcode projelerine hedef ve grup belirtimi ile dosya ekleme
• Workspace belgelerini ayrıştırarak ilişkili projeleri bulma
• Projelerde ve workspace'lerde mevcut scheme'leri listeleme

Dosya İşlemleri

• Farklı encodinglar ile dosya okuma/yazma
• Base64 encoding/decoding ile binary dosyaları işleme
• Desenler ve regex kullanarak dosyalar içinde metin arama
• Dosya varlığını kontrol etme ve dosya meta verilerini alma
• Dizin yapılarını otomatik olarak oluşturma

Build & Test

• Özelleştirilebilir seçeneklerle projeleri build etme
• Ayrıntılı hata raporlaması ile testleri çalıştırma
• Potansiyel sorunlar için kodu analiz etme
• Build dizinlerini temizleme
• Dağıtım için projeleri arşivleme

CocoaPods Entegrasyonu

• Projelerde CocoaPods başlatma
• Pod'ları yükleme ve güncelleme
• Pod bağımlılıklarını ekleme ve kaldırma
• Keyfi pod komutlarını yürütme

Swift Package Manager

• Yeni Swift paketleri başlatma
• Çeşitli sürüm gereksinimlerine sahip paket bağımlılıklarını ekleme ve kaldırma
• Paketleri güncelleme ve bağımlılıkları çözme
• DocC kullanarak Swift paketleri için dokümantasyon oluşturma
• Swift paketleri için testleri çalıştırma ve build etme

iOS Simülatör Araçları

• Ayrıntılı bilgi ile mevcut simülatörleri listeleme
• Simülatörleri başlatma ve kapatma
• Simülatörlere uygulamalar yükleme ve başlatma
• Ekran görüntüleri alma ve video kaydetme
• Simülatör ayarlarını ve durumunu yönetme

Xcode Yardımcı Araçları

• xcrun aracılığıyla Xcode komutlarını yürütme
• Asset kataloglarını derleme
• Kaynak görüntülerinden uygulama ikon setleri oluşturma
• Uygulama performansını izleme
• App Store gönderimi için arşivleri dışa aktarma ve doğrulama
• Farklı Xcode sürümleri arasında geçiş yapma

Kurulum

Ön Koşullar

• Xcode 14.0 veya daha yüksek sürümü yüklü macOS
• Node.js 16 veya daha yüksek
• npm veya yarn
• Swift 5.5+ (Swift Package Manager özellikleri için)
• CocoaPods (isteğe bağlı, CocoaPods entegrasyonu için)

Kurulum Süreci

Seçenek 1: Otomatik Kurulum (Önerilen)

Kurulum ve yapılandırma işlemini otomatik hale getiren dahil edilen kurulum betiğini kullanın:

# Betiği çalıştırılabilir hale getirin
chmod +x setup.sh

# Kurulum betiğini çalıştırın
./setup.sh

Kurulum Betiğinin Yaptıkları:

1. Ortam Doğrulaması:

   • macOS üzerinde çalıştığınızı kontrol eder
   • Xcode'un yüklü ve erişilebilir olduğunu doğrular
   • Node.js (v16+) ve npm'in mevcut olduğunu doğrular
   • Ruby yüklemesini kontrol eder
   • CocoaPods yüklemesini doğrular (eksikse yüklemeyi önerir)

2. Bağımlılık Kurulumu:

   • Tüm gerekli Node.js paketlerini yüklemek için npm install çalıştırır
   • TypeScript kodunu derlemek için npm run build yürütür

3. Yapılandırma Kurulumu:

   • Yoksa bir .env dosyası oluşturur
   • Proje temel dizininiz için istekte bulunur
   • Debug loggingı etkinleştirmek isteyip istemediğinizi sorar
   • Yapılandırma tercihlerinizi kaydeder

4. Claude Desktop Entegrasyonu (İsteğe Bağlı):

   • Sunucuyu Claude Desktop için yapılandırmayı önerir
   • Claude Desktop yapılandırma dosyasını oluşturur veya günceller
   • Sunucuyu başlatmak için uygun komut ve argümanları ayarlar

Kurulum Betiğini Ne Zaman Kullanmalı:

• İlk kurulumda tüm ön koşulların karşılandığından emin olmak için
• İnteraktif istemlerle kılavuzlu yapılandırma istediğinizde
• Claude Desktop entegrasyonunu hızlı bir şekilde ayarlamak istiyorsanız
• Ortamınızda tüm gerekli bileşenlerin olduğunu doğrulamak için

Betik sizi açık istemler ve yardımcı geri bildirimlerle yapılandırma sürecinde rehberlik edecektir.

Seçenek 2: Manuel Kurulum

Manuel Kurulumu Ne Zaman Kullanmalı:

• Her kurulum adımı üzerinde açık kontrol istiyorsanız
• Özel bir ortama veya standart olmayan bir yapılandırmaya sahipseniz
• CI/CD boru hattında veya otomatik bir ortamda kurulum yapıyorsanız
• Kurulumun belirli yönlerini özelleştirmek istiyorsanız
• Node.js projeleriyle ilgili deneyimli bir geliştirici iseniz

Manuel kurulum için bu adımları izleyin:

1. Depoyu klonlayın:

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

2. Ön koşulları doğrulayın (bunlar yüklü olması gerekir):

   • Xcode ve Xcode Command Line Tools
   • Node.js v16 veya daha yüksek
   • npm
   • Ruby (CocoaPods desteği için)
   • CocoaPods (isteğe bağlı, pod ile ilgili özellikler için)

3. Bağımlılıkları yükleyin:

   npm install
   

4. Projeyi build edin:

   npm run build
   

5. Bir yapılandırma dosyası oluşturun:

   # Seçenek A: Örnek yapılandırmayla başlayın
   cp .env.example .env
   
   # Seçenek B: Minimal bir yapılandırma oluşturun
   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
   echo "DEBUG=false" >> .env
   

   .env dosyasını tercih ettiğiniz yapılandırmayı ayarlamak için düzenleyin.

6. Claude Desktop entegrasyonu için (isteğe bağlı):

   • ~/Library/Application Support/Claude/claude_desktop_config.json dosyasını düzenleyin veya oluşturun
   • Aşağıdaki yapılandırmayı ekleyin (yolları gerektikçe ayarlayın):

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
       }
     }
   }
   

Kurulum Sorunlarını Giderme

Yaygın Kurulum Sorunları:

1. Build Hataları:

   • Doğru Node.js sürümüne sahip olduğunuzdan emin olun (v16+)
   • node_modules dosyasını silmeyi ve npm install komutunu tekrar çalıştırmayı deneyin
   • npx tsc --noEmit ile TypeScript hatalarını kontrol edin
   • Koddaki tüm import'ların düzgün şekilde çözüldüğünden emin olun

2. Eksik Bağımlılıklar:

   • Eksik modüller hakkında hataları görürseniz npm install komutunu tekrar çalıştırın
   • Native bağımlılıklar için Xcode Command Line Tools'a ihtiyacınız olabilir: xcode-select --install

3. İzin Sorunları:

   • Kurulum dizinine yazma izniniz olduğundan emin olun
   • CocoaPods kurulumu için sudo gem install cocoapods kullanmanız gerekebilir

4. Yapılandırma Sorunları:

   • .env dosyasının doğru formata ve geçerli yollara sahip olduğunu doğrulayın
   • PROJECTS_BASE_DIR öğesinin mevcut bir dizine işaret ettiğinden emin olun
   • Yolun kaçış gerektiren özel karakterler içermediğini kontrol edin

5. Claude Desktop Entegrasyonu:

   • Claude yapılandırmasındaki yolun index.js dosyasının doğru konumunu gösterdiğinden emin olun
   • Yapılandırma değişikliklerinden sonra Claude Desktop'ı yeniden başlatın
   • Sunucuyu Claude ile kullanmaya çalışmadan önce çalıştığını kontrol edin

Kullanım

Sunucuyu Başlatma

npm start

Otomatik yeniden başlama ile geliştirme modu için:

npm run dev

Yapılandırma Seçenekleri

Sunucuyu iki şekilde yapılandırebilirsiniz:

1. .env dosyasındaki ortam değişkenleri:

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

2. Komut satırı argümanları:

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

Temel Yapılandırma Parametreleri

• PROJECTS_BASE_DIR / --projects-dir: Proje temel dizini (gerekli)
• ALLOWED_PATHS / --allowed-paths: Erişim izni verilecek ek dizinler (virgülle ayrılmış)
• PORT / --port: Sunucunun çalışacağı port (varsayılan: 3000)
• DEBUG / --debug: Debug loggingı etkinleştirme (varsayılan: false)
• LOG_LEVEL / --log-level: Logging seviyesini ayarlama (varsayılan: info)

AI Asistanlarına Bağlanma

Sunucu Model Context Protocol'ü (MCP) uygular ve bu protokolü destekleyen çeşitli AI asistanlarıyla uyumludur. Bağlanmak için:

1. Xcode MCP sunucusunu başlatın
2. AI asistanınızı sunucu URL'sini kullanacak şekilde yapılandırın (genellikle http://localhost:3000)
3. AI asistanı artık sunucu tarafından sağlanan tüm Xcode araçlarına erişebilecektir

Araç Belgelendirmesi

Tüm kullanılabilir araçlar ve bunların kullanımı hakkında kapsamlı bir genel bakış için Araçlar Özeti bölümüne bakın.

Ayrıntılı kullanım örnekleri ve en iyi uygulamalar için Kullanıcı Rehberi bölümüne bakın.

Yaygın İş Akışları

Yeni Bir Proje Kurma

// Yeni bir iOS uygulama projesi oluşturma
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// Swift Package bağımlılığı ekleme
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

Dosyalarla Çalışma

// Dosyayı belirli encoding ile okuma
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

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

// Dosyalar içinde metin arama
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

Build ve Test

// Projeyi build etme
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// Testleri çalıştırma
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

Proje Yapısı

xcode-mcp-server/
├── src/
│   ├── index.ts                 # Giriş noktası
│   ├── server.ts                # MCP sunucu uygulaması
│   ├── types/                   # Tip tanımları
│   │   └── index.ts             # Temel tip tanımları
│   ├── utils/                   # Yardımcı fonksiyonlar
│   │   ├── errors.js            # Hata işleme sınıfları
│   │   ├── pathManager.ts       # Yol doğrulama ve yönetimi
│   │   ├── project.js           # Proje yardımcı araçları
│   │   └── simulator.js         # Simülatör yardımcı araçları
│   └── tools/                   # Araç uygulamaları
│       ├── project/             # Proje yönetimi araçları
│       │   └── index.ts         # Proje oluşturma, algılama, dosya ekleme
│       ├── file/                # Dosya işlemi araçları
│       │   └── index.ts         # Dosya okuma, yazma, arama
│       ├── build/               # Build ve test araçları
│       │   └── index.ts         # Build, test, analiz
│       ├── cocoapods/           # CocoaPods entegrasyonu
│       │   └── index.ts         # Pod yükleme ve yönetimi
│       ├── spm/                 # Swift Package Manager araçları
│       │   └── index.ts         # Paket yönetimi ve belgelendirmesi
│       ├── simulator/           # iOS simülatör araçları
│       │   └── index.ts         # Simülatör kontrolü ve etkileşimi
│       └── xcode/               # Xcode yardımcı araçları
│           └── index.ts         # Xcode sürüm yönetimi, asset araçları
├── docs/                        # Belgelendirme
│   ├── tools-overview.md        # Kapsamlı araç belgelendirmesi
│   └── user-guide.md            # Kullanım örnekleri ve en iyi uygulamalar
├── tests/                       # Testler
└── dist/                        # Derlenmiş kod (oluşturulmuş)

Nasıl Çalışır

Xcode MCP sunucusu, AI modellerinin Xcode projeleriyle etkileşim kurması için standartlaştırılmış bir arayüz sağlamak üzere Model Context Protocol'ü kullanır. Sunucu mimarisi birkaç önemli bileşenle tasarlanmıştır:

Temel Bileşenler

1. Sunucu Uygulaması: Araç kaydını ve istek işlemeyi işleyen ana MCP sunucusu.

2. Yol Yönetimi: Tüm yolları izin verilen dizinlere karşı doğrulayarak güvenli dosya erişimini sağlar.

3. Proje Yönetimi: Farklı Xcode proje türlerini algılar, yükler ve yönetir:

   • Standart Xcode projeleri (.xcodeproj)
   • Xcode workspace'leri (.xcworkspace)
   • Swift Package Manager projeleri (Package.swift)

4. Dizin Durumu: Bağıl yol çözümlemesi için aktif dizin bağlamını tutar.

5. Araç Kayıt Sistemi: Araçları farklı Xcode işlemleri için mantıksal kategoriler halinde düzenler.

İstek Akışı

1. Bir AI asistanı MCP sunucusuna araç yürütme isteği gönderir.

2. Sunucu istek parametrelerini ve izinleri doğrular.

3. Doğrulanan parametrelerle uygun araç işleyicisi çağrılır.

4. Araç istenen işlemi yürütür, sıklıkla native Xcode komutlarını kullanır.

5. Sonuçlar biçimlendirilir ve AI asistanına döndürülür.

6. Kapsamlı hata işleme sorun giderme için anlamlı geri bildirim sağlar.

Güvenlik Özellikleri

• Yol Doğrulama: Tüm dosya işlemleri izin verilen dizinlerle sınırlıdır.
• Hata İşleme: Ayrıntılı hata mesajları sorunları teşhis etmeye yardımcı olur.
• Parametre Doğrulama: Giriş parametreleri Zod şemaları kullanılarak doğrulanır.
• İşlem Yönetimi: Harici işlemler uygun hata işleme ile güvenli şekilde yürütülür.

Proje Türü Desteği

Sunucu farklı proje türlerini akıllıca işler:

• Standart Projeler: Doğrudan .xcodeproj manipülasyonu
• Workspace'ler: Workspace içindeki çoklu projeleri yönetir
• SPM Projeleri: Swift Package Manager'a özgü işlemleri işler

Bu mimari, AI asistanlarının güvenliği ve ayrıntılı geri bildirim sağlarken herhangi bir Xcode proje türü ile sorunsuz çalışmasını sağlar.

Katkı Yapma

Katkılar memnuniyetle karşılanır! Lütfen bir Pull Request göndermekten çekinmeyin.

1. Depoyu fork'layın
2. Özellik dalınızı oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add some amazing feature')
4. Dala push edin (git push origin feature/amazing-feature)
5. Bir Pull Request açın

Geliştirme Yönergeleri

• Mevcut kod stilini ve organizasyonunu izleyin
• Belirli hata mesajları ile kapsamlı hata işleme ekleyin
• Yeni işlevsellik için testler yazın
• Belgelendirmeyi değişikliklerinizi yansıtacak şekilde güncelleyin
• Farklı proje türleriyle (standart, workspace, SPM) uyumluluğu sağlayın

Yeni Araçlar Ekleme

Sunucuya yeni bir araç eklemek için:

1. src/tools/ dizininde uygun kategoriyi belirleyin
2. Zod şema doğrulama ile mevcut desenleri kullanarak aracı uygulayın
3. Aracı kategorinin index.ts dosyasına kaydedin
4. Belirli hata mesajları ile hata işleme ekleyin
5. Aracı uygun belgelendirme dosyalarında belgelendir

Sorun Giderme

Yaygın Sorunlar

• Yol Erişim Hataları: Erişmeye çalıştığınız yolların izin verilen dizinler içinde olduğundan emin olun
• Build Başarısızlıkları: Xcode command line tools'un yüklü ve güncel olduğunu kontrol edin
• Araç Bulunamadı: Araç adının doğru olduğunu ve düzgün şekilde kaydettiğini doğrulayın
• Parametre Doğrulama Hataları: Araç belgelendirmesinde parametre türlerini ve gereksinimlerini kontrol edin

Hata Ayıklama

1. Debug loggingı etkin olarak sunucuyu başlatın: npm start -- --debug
2. Ayrıntılı hata mesajları için konsol çıktısını kontrol edin
3. İstek ve yanıt ayrıntıları için sunucu loglarını inceleyin
4. Araç'a özgü sorunlar için eşdeğer Xcode komutunu doğrudan terminalden çalıştırmayı deneyin

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - Ayrıntılar için LICENSE dosyasına bakın.

Teşekkürler

• Model Context Protocol ekibine MCP SDK için teşekkür ederiz
• TypeScript ve Node.js ile yapılmıştır
• Xcode command line tools ve Swift Package Manager kullanır
• Sunucunun işlevselliğini ve sağlamlığını iyileştirmeye yardımcı olan tüm katılımcılara özel teşekkürler