🍎📚 Cupertino

🕯️ v1.2.1 sürümü 2026-05-23 tarihinde yayınlandı. Bakım sürümü: mimari temizlik + DI / pluggability iyileştirmesi. v1.2.0'a göre sıfır şema farkı; v1.2.0 paketi v1.2.1 binary'si ile olduğu gibi çalışır (cupertino setup hala cupertino-databases-v1.2.0.zip indirir). Başlıklar: Source Independence Day ulaşıldı (yeni bir content source eklemek artık yalnızca composition-root PR'ıdır); strict-DI + standalone-portability epic kapatıldı (her Search-side producer foundation-only, scripts/check-target-portability.sh tarafından mekanik olarak doğrulanmıştır); Distribution.DatabaseHealthCheck strategy seam, Doctor'ın 3 kardeş per-DB bölümünü kapsar. Canlı dashboard https://cupertino.aleahim.com/ adresinde. v1.2.1 sürüm notlarına bakın.

v1.2.0 "ironclad" (2026-05-20) en son paket sürümüydü. Arama kalitesi sürümü: kanonik arama sorgularında rank-1 doğruluğu Phase 1 corpus'unda %52'den %92'ye sıçradı, 110 eşleştirilmiş sorgu arasında sıfır regresyon, deprecation-pair corpus'unda 30 / 30 modern Swift kazanımı. databaseVersion 1.2.0'dır: cupertino setup cupertino-databases-v1.2.0.zip indirir (690 MiB sıkıştırılmış, sha256 097d6633…f47747) 420 framework arasında 352,712 indeksli belge taşır, search.db user_version 18, packages.db 5, samples.db 4, 13 kategori denetimi arasında 0 poison satırı. Tam yazı docs/release-writeup-v1.2.0.md dosyasında. v1.2.0 sürüm notlarına bakın.

Apple Dokümantasyon Crawler & MCP Sunucusu

Apple geliştirici dokümantasyonunu indeksleyen ve Model Context Protocol (MCP) üzerinden AI ajanlarına sunan Swift tabanlı bir araç.

Cupertino Demo

Cupertino Nedir?

Cupertino, Apple platformları için yerel, yapılandırılmış, AI'ya hazır bir dokümantasyon sistemidir. Şunları yapar:

İndeksler Apple Developer dokümantasyonunu, Swift.org'u, Swift Evolution öneri tekliflerini, Human Interface Guidelines'ı, Apple Archive legacy rehberlerini ve Swift paket metadatasını
İndeksler her şeyi hızlı, aranabilir SQLite FTS5 veritabanına alan ağırlıklı BM25 (BM25F) sıralaması ve AST-çıkarılmış symbol sütunlarıyla
Sunar dokümantasyonu Model Context Protocol aracılığıyla Claude gibi AI ajanlarına
Sağlar 420 framework arasında 352.712+ dokümantasyon sayfasına çevrimdışı erişim (v1.2.0 paketi)

Neden Bunu İnşa Ettik?

Artık halüsinasyon yok: AI ajanları doğru, güncel Apple API dokümantasyonunu alırlar
Çevrimdışı geliştirme: İnternet bağlantısı olmadan tam dokümantasyonla çalışın
Belirleyici arama: Aynı sorgu her zaman aynı sonuçları döndürür
Yerel kontrol: Dokümantasyonunuza sahip olun, veritabanını inceleyin, iş akışlarını otomatikleştirin
AI-first tasarım: MCP aracılığıyla AI ajan entegrasyonu için özel olarak inşa edilmiştir

Hızlı Başlangıç

Not: Kaynaktan derlerken, komutlar Packages dizininden çalıştırılmalıdır. Tek komut kurulumu her yerden çalışır.

Gereksinimler

macOS 15+ (Sequoia)
Tam v1.2.0 paketi için ~4,1 GB disk alanı (search.db ~2,87 GB, packages.db ~1,06 GB, samples.db ~187 MB; sıkıştırılmış indirme ~690 MiB)

Kaynaktan derleme ayrıca Swift 6.3+ ve Xcode 26+ gerektirir (bare swift değil xcrun swift build kullanın)

Kurulum

Tek komut kurulumu (önerilen):

bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Bu, önceden derlenmiş, imzalı ve noterize evrensel bir binary indirir, /usr/local/bin'e kurar ve dokümantasyon veritabanlarını indirir.

Ya da Homebrew ile:

brew tap mihaelamj/tap
brew install cupertino
cupertino setup

Ya da kaynaktan derleyin:

git clone https://github.com/mihaelamj/cupertino.git
cd cupertino

# Makefile kullanarak (önerilen)
make build                       # Release binary'si derle
sudo make install                # /usr/local/bin'e kur

# Ya da Swift Package Manager'ı doğrudan kullanın
cd Packages
swift build -c release
sudo ln -sf "$(pwd)/.build/release/cupertino" /usr/local/bin/cupertino

Demo Video: YouTube'da İzle

Hızlı Referans

# Hızlı Kurulum (Önerilen) - önceden derlenmiş veritabanlarını indir (~30 saniye)
cupertino setup                      # Veritabanlarını GitHub'dan indir
cupertino serve                      # MCP sunucusunu başlat

# Alternatif: GitHub'dan derle (~45 dakika)
cupertino save --remote              # Akış ve yerel olarak derle

# Ya da dokümantasyonu kendiniz getirin
cupertino fetch --type docs          # Apple Developer Dokümantasyonu
cupertino fetch --type swift         # Swift.org dokümantasyonu
cupertino fetch --type evolution     # Swift Evolution teklifleri
cupertino fetch --type packages      # Swift paket metadatası + GitHub arşivleri
cupertino fetch --type code          # Apple'dan örnek kod (kimlik doğrulaması gerekli)
cupertino fetch --type samples       # GitHub'dan örnek kod (önerilen)
cupertino fetch --type archive       # Apple Archive programlama rehberleri
cupertino fetch --type hig           # Human Interface Guidelines
cupertino fetch --type availability  # Platform kullanılabilirlik verileri
cupertino fetch --type all           # Tüm türler paralel olarak

# İndeksleri derle
cupertino save                       # Dokümantasyon arama indeksi derle (yerel dosyalardan)
cupertino save --remote              # GitHub'dan derle (yerel dosya gerekmez)
cupertino save --samples                      # Örnek kodu arama için indeksle

# Sunucuyu başlat
cupertino                            # MCP sunucusunu başlat (varsayılan komut)
cupertino serve                      # MCP sunucusunu başlat (açık)

Anlık Kurulum (Önerilen)

# GitHub'dan önceden derlenmiş veritabanlarını indir (~30 saniye)
cupertino setup

# MCP sunucusunu başlat
cupertino serve

Not: cupertino setup --force artık geçersizdir (bayrak v1.2.0'da kaldırıldı). cupertino setup varsayılan olarak üzerine yazar; veritabanlar zaten yüklüyse indirmeyi atlamak için --keep-existing iletişim kurun.

Alternatif: GitHub'dan Derle

# Yerel olarak akış ve derle (~45 dakika)
# Veritabanını kendiniz derlemek istiyorsanız bunu kullanın
cupertino save --remote

# MCP sunucusunu başlat
cupertino serve

Manuel Kurulum (Gelişmiş)

# Apple dokümantasyonunu indir (~12+ gün ~404.000+ ham sayfa için, ~277.640'a indekslenmiş)
# İstekler arasında varsayılan 0,05 saniye gecikmesi nedeniyle zaman alır
cupertino fetch --type docs --max-pages 15000

# Swift Evolution tekliflerini indir (~2-5 dakika)
cupertino fetch --type evolution

# GitHub'dan örnek kod indir (~4 dakika, 619 proje)
cupertino fetch --type samples

# Arama indeksi derle (~2-5 dakika)
cupertino save

Claude Desktop ile Kullanım

Claude Desktop'ı Yapılandır - ~/Library/Application Support/Claude/claude_desktop_config.json dosyasını düzenle:

{
  "mcpServers": {
    "cupertino": {
      "command": "/usr/local/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Not: Apple Silicon için Homebrew'de /opt/homebrew/bin/cupertino kullanın, Intel veya manuel kurulum için /usr/local/bin/cupertino. Yolunuzu bulmak için which cupertino çalıştırın.

Claude Desktop'ı Yeniden Başlat
Claude'dan Apple API'leri hakkında sorun:
- "SwiftUI dokümantasyonunu ara"
- "Swift Evolution teklifinin SE-0001 ne önerdiğini?"
- "Kullanılabilir framework'leri listele"

Claude Code ile Kullanım

Claude Code kullanıyorsanız, Cupertino'yu tek bir komutla MCP sunucusu olarak ekleyebilirsiniz:

claude mcp add cupertino --scope user -- $(which cupertino)

Bu, Cupertino'yu tüm projeleriniz için global olarak kaydeder. Claude Code'un Apple dokümantasyon aramasına otomatik olarak erişimi olacak.

OpenAI Codex ile Kullanım

OpenAI Codex kullanıyorsanız, Cupertino'yu şu şekilde ekleyin:

codex mcp add cupertino -- $(which cupertino) serve --no-reap

Ya da doğrudan ~/.codex/config.toml dosyasına ekleyin:

[mcp_servers.cupertino]
command = "/opt/homebrew/bin/cupertino"  # Apple Silicon'da Homebrew
# command = "/usr/local/bin/cupertino"   # Intel Mac veya manuel kurulum
args = ["serve", "--no-reap"]

Neden --no-reap? Codex, her tool çağrısı başına yeni bir cupertino serve başlatır. --no-reap olmadan, her yeni örnek öncekini eski bir sibling olarak öldürür ve uçuştaki transport kapanır (Transport closed hatası her tool çağrısında — bkz #280). Claude Desktop / Cursor kullanıcıları varsayılanı tutarlar (reap açık) böylece MCP-host konfigürasyonu yeniden yüklemesi yetim sunucuları sızdırmaz.

Eşdeğer env-var formu: [mcp_servers.cupertino.env] içinde CUPERTINO_DISABLE_REAPER=1.

İpucu: Kurulum yolunuzu bulmak için which cupertino çalıştırın.

Cursor ile Kullanım

Projenizde .cursor/mcp.json dosyasına (ya da global erişim için ~/.cursor/mcp.json) ekleyin:

{
  "mcpServers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

VS Code ile Kullanım (GitHub Copilot)

Çalışma alanınıza .vscode/mcp.json dosyasına ekleyin:

{
  "servers": {
    "cupertino": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

GitHub Copilot for Xcode ile Kullanım

GitHub Copilot for Xcode, Agent Mode aracılığıyla MCP sunucularını destekler. Uygulamada Tools sekmesine → MCP alt sekmesine → MCP Configuration → Edit Config gidin veya doğrudan ~/.config/github-copilot/xcode/mcp.json dosyasını düzenleyin:

{
  "servers": {
    "cupertino": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Zed ile Kullanım

Zed settings.json dosyanıza ekleyin:

{
  "context_servers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Windsurf ile Kullanım

~/.codeium/windsurf/mcp_config.json dosyasına ekleyin:

{
  "mcpServers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

opencode ile Kullanım

opencode.jsonc dosyasına ekleyin:

{
  "mcp": {
    "cupertino": {
      "type": "local",
      "command": ["/opt/homebrew/bin/cupertino", "serve"]
    }
  }
}

Not: Tüm örnekler /opt/homebrew/bin/cupertino (Apple Silicon'da Homebrew) kullanır. Intel Mac'ler veya manuel kurulumlar için /usr/local/bin/cupertino kullanın. Yolunuzu bulmak için which cupertino çalıştırın.

Agent Skill Olarak Kullanım (Sunucu Gerekmez)

Cupertino, MCP sunucusu çalıştırmadan durumsuz CLI skill olarak da kullanılabilir. Bu, Agent Skills spesifikasyonunu destekleyen ajanlar için kullanışlıdır.

Ön Koşullar:

Cupertino'yu kurun ve veritabanlarını önceden indirin:

# Homebrew'den veya kaynaktan kurun (yukarıdaki Kurulum bölümüne bakın)
cupertino setup

Seçenek A: OpenSkills ile Kurun (Önerilen)

OpenSkills, Claude Code, Cursor, Windsurf, Aider ve diğer AI kodlama ajanlarıyla çalışan evrensel bir skills yükleyicidir.

# Cupertino skill'ini GitHub'dan kurun
npx openskills install mihaelamj/cupertino

# Senkronize etmek için güncelle AGENTS.md
npx openskills sync

Global kurulum için (tüm projelerde kullanılabilir):

npx openskills install mihaelamj/cupertino --global

Multi-ajan kurulumları için (.agent/skills/ yerine .claude/skills/ 'e kurar):

npx openskills install mihaelamj/cupertino --universal

Seçenek B: Claude Code Plugin Olarak Kurun

Bir Claude Code oturumunun içinde, cupertino pazarını ekleyin:

/plugin marketplace add mihaelamj/cupertino

Ardından pazardan plugin'i etkinleştirin.

Seçenek C: Manuel Kurulum

Skill tanımını projenize veya global skills dizinine kopyalayın:

# Bu repo'yu klonla
git clone https://github.com/mihaelamj/cupertino.git

# Tek bir proje için
mkdir -p .claude/skills/cupertino
cp cupertino/skills/cupertino/SKILL.md .claude/skills/cupertino/

# Veya Claude Code ile global kullanım için
mkdir -p ~/.claude/skills/cupertino
cp cupertino/skills/cupertino/SKILL.md ~/.claude/skills/cupertino/

Nasıl Çalışır:

Skill, hiçbir sunucu süreci gerekmeden CLI'yi JSON çıktısıyla doğrudan kullanır:

# Dokümantasyonu ara
cupertino search "SwiftUI View" --format json

# Kaynak tarafından filtrele
cupertino search "NavigationStack" --source apple-docs --format json
cupertino search "button styles" --source samples --format json

# Belge oku
cupertino read "apple-docs://swiftui/documentation_swiftui_view" --format json

# Framework'leri listele
cupertino list-frameworks --format json

# Örnek projeleri listele
cupertino list-samples --framework swiftui --format json

Tüm komutlar ajanların ayrıştırabileceği yapılandırılmış çıktı için --format json destekler.

Kullanılabilir Kaynaklar:

apple-docs - Resmi Apple dokümantasyonu (~352.712 sayfası v1.2.0'da indekslenmiş)
samples - Apple örnek kod projeleri
hig - Human Interface Guidelines
swift-evolution - Swift Evolution teklifleri
swift-org - Swift.org dokümantasyonu
swift-book - The Swift Programming Language kitabı
apple-archive - Legacy programlama rehberleri
packages - Swift paket dokümantasyonu

Nedeni Alırsınız

Yapılandırıldıktan sonra, Claude Desktop yerel dokümantasyonunuzu arayabilir:

Arama Sonuçları Örneği:

# "SwiftUI" için Arama Sonuçları

**20** sonuç bulundu:

## 1. NSHostingView | Apple Developer Dokümantasyonu
- **Framework:** `swiftui`
- **URI:** `apple-docs://swiftui/documentation_swiftui_nshostingview`
- **Puan:** 1.82

Bir SwiftUI view hiyerarşisini barındıran bir AppKit view'i.

## 2. UIHostingController | Apple Developer Dokümantasyonu
- **Framework:** `swiftui`
- **URI:** `apple-docs://swiftui/documentation_swiftui_uihostingcontroller`

Bir SwiftUI view hiyerarşisini yöneten bir UIKit view controller'ı.
...

Framework İstatistikleri:

Framework	Belgeler
Kernel	39.396
Matter	24.320
Swift	17.466
AppKit	12.443
Foundation	12.423
UIKit	11.158
Accelerate	9.114
SwiftUI	7.062
...	...
420 Framework	352.712

Temel Özellikler

1. Multi-Kaynak Dokümantasyon Getirme

Apple Developer Dokümantasyonu (~v1.2.0 paketinde 352.712 indeksli sayfa)
- WKWebView aracılığıyla JavaScript farkında rendering
- HTML'den Markdown'a dönüştürme
- Akıllı değişiklik algılaması
Swift Evolution Teklifleri (~400 teklif)
- GitHub tabanlı getirme
- Markdown format
- Hızlı indirmeler
Swift.org Dokümantasyonu
- Resmi Swift dil doğruları
- Temiz HTML yapısı
Swift Paket Metadatası
- Öncelikli paket kataloğları
- README dosyaları
Apple Örnek Kodu (619 proje)
- İki getirme yöntemi: GitHub (önerilen) veya Apple web sitesi
- Tüm kaynak dosyaları arasında tam metin araması
- 18.000+ indeksli Swift dosyası
Apple Archive Legacy Rehberleri (~75 sayfa)
- 2016 öncesi programlama rehberleri (Core Animation, Quartz 2D, Core Text, vb.)
- Modern doğrularda olmayan derin kavramsal bilgi
- Aramadan hariç tutulmuş (kullanmak için --include-archive kullanın)
Human Interface Guidelines
- Apple'ın tüm platformlar için resmi tasarım rehberleri
- iOS, macOS, watchOS, visionOS ve tvOS'u kapsar
- Tasarım desenleri, bileşenler, temel kavramlar ve en iyi uygulamalar

2. Paketlenmiş Kaynaklar

Cupertino, doğrudan uygulamaya paketlenmiş önceden indekslenmiş katalog verilerini içerir:

Swift Packages Kataloğu (183 Apple resmi paketi tam kaynak + packages.db'de metaveri; önceki 9.699 girişli gömülü URL listesi #194'te kaldırıldı — packages.db artık kanonik corpus, cupertino setup aracılığıyla sevk edilir)
- Swift Package Index + GitHub API'den kuratörlü
- Paket metadatası, yıldızlar, lisanslar, açıklamalar, dağıtım hedefi platformları, ve yazılı swift-tools-version (#225) içerir
- cupertino fetch --type packages ardından cupertino save --packages çalıştırılarak güncellendi
Örnek Kod Kataloğu (619 giriş)
- Apple'ın resmi örnek kod projeleri
- Başlıklar, açıklamalar, framework'ler, indirme URL'lerini içerir
- Apple'ın kataloğu sık sık değişmediği için paketlenmiş
Öncelikli Paketler (36 küratörlü paket)
- Apple resmi paketleri (31) + gerekli ekosistem paketleri (5)
- Hızlı erişim için yüksek öncelikli Swift paketleri

Bu kataloglar cupertino save sırasında indekslenmiş ve çok saatlik indirmeler gerektirmeden anlık arama sağlar. İsterseniz cupertino fetch aracılığıyla paket README'leri ve örnek kodu ayrı olarak getirtebilirsiniz.

3. Tam Metin Arama Motoru

Teknoloji: SQLite FTS5'i 9 sütunlu indeks (uri, source, framework, language, title, content, summary, symbols, symbol_components) üzerinde alan ağırlıklı BM25 (BM25F, Robertson/Zaragoza/Taylor 2004) ile. Başlık 10×, AST-çıkarılmış symbols 5×, summary 3×, framework 2×, CamelCase bölme symbol bileşenleri 1,5×.
AST farkında: Bir Swift kaynak çıkarıcı, gömülü her kod bloğundan ve sayfa beyanından tanımlayıcıları çıkarır, bunları symbols sütununa denormalize eder ve BM25F'ye besler, böylece Task gibi bir sorgu Swift Task struct'ını "task" sözcüğünün prose söylemleri üzerine yerleştirir.
smart-query: cupertino search (ve alttaki Search.SmartQuery API'si) soruyu her kaynakta paralel olarak hayran hali ve reciprocal rank fusion (RRF, k=60, Cormack/Clarke/Büttcher 2009) aracılığıyla per-kaynağı sıralamaları birleştirir. Tek ölü kaynak tüm sorguyu asla aşağı çekmez.
Özellikler:
- Porter stemming (örneğin "çalıştırmak" "çalış" ile eşleşir)
- Framework filtrelemesi
- Platform kullanılabilirlik filtrelemesi (iOS/macOS versiyonu)
- Snippet oluşturması
- Alt-100ms sorgu performansı
Boyut: Tam dokümantasyon için ~2,87 GB search.db + ~1,06 GB packages.db + ~187 MB samples.db (352.712 belge 420 framework arasında, v1.2.0 paketi)
Depolama: Veritabanı yerel dosya sisteminde olmalıdır - SQLite ağ sürücülerinde (NFS/SMB) güvenilir şekilde çalışmaz

4. Model Context Protocol Sunucusu

Kaynaklar: Dokümantasyon sayfalarına doğrudan erişim
- apple-docs://{framework}/{page}
- swift-evolution://{proposal-id}
- hig://{category}/{page}
Araçlar: AI ajanları için arama ve okuma yetenekleri
- Dokümantasyon Araçları (cupertino save gerektirir):
  - search - Birleştirilmiş tam metin araması her indeksli kaynak arasında: Apple Developer Dokümantasyonu, örnek kod, Human Interface Guidelines, Apple Archive, Swift Evolution, swift.org, Swift Kitabı ve Swift paket metadatası. #239 öncesi per-kaynak araçlarını (search_docs, search_hig, search_samples, search_all) değiştirir.
    - Parametreler: query (gerekli), source (isteğe bağlı: all, apple-docs, samples, hig, apple-archive, swift-evolution, swift-org, swift-book, packages), framework, language, include_archive, limit, min_ios, min_macos, min_tvos, min_watchos, min_visionos, min_swift (tüm isteğe bağlı)
    - Platform filtrelemesi (#226, #732): 5 min_* parametresi, platform kullanılabilirlik metadatası taşıyan her kaynağa uygulanır (apple-docs, apple-archive, packages, swift-evolution, swift-org, swift-book, samples). Multi-platform değerleri AND-combine (örn. min_ios=18.0 + `min_macos=14

mihaelamj/cupertino

Bu MCP sunucusu hakkında