Integracja z systemem od środka

Aplikacje produktywnościowe na stacji roboczej (Kalendarz, Poczta, Przypomnienia i Notatki) korzystają wyłącznie z API systemu operacyjnego hosta. Ponieważ kontenery nie mają bezpośredniego dostępu do frameworków Apple, Speedwave uruchamia proces mcp-os jako natywną usługę hosta, a nie skonteneryzowanego workera. Przegląd funkcjonalny znajdziesz na stronie Integracje systemowe.

Architektura pośredniczenia procesu hosta

Claude nigdy nie łączy się bezpośrednio z usługą mcp-os. Wszystkie wywołania narzędzi trafiają do Tool Gatewaya (Hubu MCP), który przekazuje żądania do procesu na hoście przez interfejs host.docker.internal:

graph LR
  C["Claude Code (Kontener piaskownicy)"] --> H["Tool Gateway (Hub MCP)"]
  H -->|"host.docker.internal:PORT"| OS["mcp-os (Proces hosta)"]
  OS -->|"posix_spawn"| CLI["Natywny helper w Swift"]
  CLI -->|"EventKit / Apple Events"| APP["Kalendarz, Przypomnienia, Poczta, Notatki"]

Implementacja na platformach systemowych

macOS

W systemie macOS usługa mcp-os wywołuje cztery niezależne pliki binarne w języku Swift wykorzystujące natywne frameworki Apple:

Plik binarny	Framework Apple	Zakres operacji
reminders-cli	EventKit	Odczyt, tworzenie oraz oznaczanie przypomnień jako zakończone.
calendar-cli	EventKit	Pełne zarządzanie wydarzeniami w Kalendarzu (CRUD).
mail-cli	AppleScript / Apple Events	Odczyt, tworzenie szkiców i bezpieczne wysyłanie wiadomości w Apple Mail i Outlook.
notes-cli	AppleScript / Apple Events	Odczyt i tworzenie notatek w Apple Notes (CRUD).

Pomocnicze pliki wykonywalne są uruchamiane przez posix_spawn, co izoluje błędy frameworków od głównego procesu aplikacji.

Windows

Integracja z systemem Windows jest obecnie rozwijana jako samodzielny moduł w języku Rust wykorzystujący interfejsy WinRT oraz API MAPI programu Outlook.

Model sieciowy i mechanizmy bezpieczeństwa

• Dynamiczne porty efemeryczne: Demon mcp-os uruchamia się z parametrem PORT=0, przypisując wolny port przydzielony przez jądro systemu i rejestrując go w Tool Gatewayu.
• Wiązanie z interfejsem loopback: W systemie macOS proces nasłuchuje ściśle na adresie 127.0.0.1 (lub IP adaptera WSL w Windows), nigdy nie otwierając portu 0.0.0.0.
• Autoryzacja tokenem sesyjnym: Każde żądanie wymaga przesłania unikalnego tokenu bearer wygenerowanego podczas startu środowiska.
• Apple Hardened Runtime: Pomocnicze pliki binarne w Swift działają w trybie Hardened Runtime, posiadając deklarowane uprawnienia (entitlements) wyłącznie do API Apple Events i EventKit.

Zarządzanie uprawnieniami TCC (macOS)

Dostęp do natywnych zasobów w macOS podlega kontroli mechanizmu Transparency, Consent and Control (TCC). Pomocnicze pliki binarne posiadają unikalne identyfikatory pakietów wymagane do poprawnego wyświetlania systemowych okien dialogowych zgody. Szczegóły opisano w rozdziale Uprawnienia systemowe (TCC) na macOS.