apple-docs-mcp

Serwer MCP i CLI przeszukujący Apple Developer Documentation z indeksu na dysku Xcode — w pełni offline, bez wywołań sieciowych.

Po co istnieje

Agenci kodujący przypominają sobie API Apple z danych treningowych, które zostają za zainstalowanym SDK. Xcode już przechowuje lokalną kopię dokumentacji, ale tekstu nie da się w niej odczytać: index.json zawiera węzły nawigacji bez treści, cache.db trzyma skompresowane bloby, których nagłówek nie dekoduje się ani przez LZ4, ani LZFSE, zlib, LZMA czy LZBITMAP, a documentation-db/index.sql to magazyn wektorowy dla wyszukiwania semantycznego Xcode, nie tekst. Ten serwer udostępnia prawdziwy tekst: sygnatury, dostępność i przykłady kodu.

Co robi

• search_docs: wyszukiwanie po znaczeniu, zwracające pełny tekst, przykłady kodu, uri i wynik dla każdego trafienia
• list_frameworks: wszystkie frameworki z lokalnego indeksu (~395), offline, bez zatwierdzenia
• doc_status: informuje, czy wyszukiwanie działa teraz, a jeśli nie — dlaczego
• CLI z wyjściem --json i osobnym kodem wyjścia dla każdej klasy błędu

Stack

• Python
• uv
• Model Context Protocol
• Xcode mcpbridge

Użycie

claude mcp add apple-docs --scope user -- \
  uv run --quiet --project /path/to/apple-docs-mcp apple-docs-mcp
apple-docs search "SwiftData model inheritance" --framework SwiftData
apple-docs search "AVAudioSession category" --json
apple-docs frameworks
apple-docs status

Notatki inżynierskie

Zmierzone zachowanie mostka, który opakowuje: 19–20 dokumentów na zapytanie z pełną treścią i przykładami kodu, około 0,4 s mediany opóźnienia i zero bajtów ruchu sieciowego. Kłopotliwa część jest opisana, a nie ukryta: search_docs napędza mcpbridge, więc Xcode musi działać z zatwierdzonym obszarem roboczym, zatwierdzenie jest przyznawane na proces, a nie na użytkownika, i wygasa po 24 godzinach. Każdy błąd zwraca typowany komunikat wraz z rozwiązaniem, a narzędzie nigdy nie sygnalizuje problemu pustą listą, bo pusty wynik jest nieodróżnialny od braku API — dokładnie ta niejasność była powodem powstania projektu. Testy jednostkowe nie wymagają Xcode, a testy integracyjne pomijają się, gdy mostek jest nieobecny lub niezatwierdzony.

Ograniczenia

• Wymaga macOS z zainstalowanym Xcode.
• search_docs potrzebuje zatwierdzonego obszaru roboczego Xcode; zatwierdzenie dotyczy procesu i wygasa po 24 godzinach.

Źródło: Ahmetshbzz/apple-docs-mcp