# Integracja z systemem od środka

Kalendarz, Poczta, Przypomnienia i Notatki działają na hoście, czyli w systemie operacyjnym, a ich API są dostępne wyłącznie z hosta: kontener się do nich nie dostanie. Dlatego Speedwave uruchamia `mcp-os` jako proces hosta, a nie w kontenerze, jak każdy inny worker MCP (hub, Slack, Redmine i pozostałe). Ta strona pokazuje, jak żądanie dociera do natywnej aplikacji hosta i wraca, oraz jak macOS kontroluje je po drodze. Zobacz stronę [Integracje z systemem](/pl/docs/integrations/os-integrations/), żeby dowiedzieć się, do czego te integracje służą na co dzień.

## Dlaczego ten worker działa na hoście

Claude nigdy nie rozmawia z `mcp-os` bezpośrednio. MCP Hub przekazuje każde żądanie przez alias bramy `host.docker.internal`, więc pojedynczy punkt wejścia pozostaje taki sam jak przy każdym workerze w kontenerze, tyle że tym razem prowadzi przez lokalne HTTP, a nie przez sieć kontenerów.

## Przepływ żądania

Żeby dotrzeć do `mcp-os`, żądanie przekracza granicę kontenera, a `mcp-os` uruchamia następnie natywnego pomocnika, który steruje docelową aplikacją:

```mermaid
graph LR
  C["Claude (w kontenerze)"] --> H["MCP Hub (kontener)"]
  H -->|"host.docker.internal"| OS["mcp-os (proces hosta)"]
  OS -->|"posix_spawn"| CLI["natywny pomocnik CLI"]
  CLI -->|"EventKit / Apple Events"| APP["Kalendarz, Przypomnienia, Poczta, Notatki"]
```

## Implementacja na macOS

Na macOS cztery samodzielne binarki CLI napisane w Swifcie obsługują po jednej usłudze, każda korzysta z takiego frameworku, jaki akurat jest stabilny:

| Binarka | Framework | Zadanie |
| --- | --- | --- |
| `reminders-cli` | EventKit | Tworzenie i odczyt Przypomnień, plus oznaczanie jako ukończone (bez aktualizacji i usuwania) |
| `calendar-cli` | EventKit | CRUD dla wydarzeń w Kalendarzu |
| `mail-cli` | AppleScript / Apple Events | Apple Mail i Outlook: odczyt, wysyłanie i odpowiadanie (wysyłanie wymaga potwierdzenia flagą) |
| `notes-cli` | AppleScript / Apple Events | CRUD dla Apple Notes |

`mcp-os` wywołuje tych pomocników w czasie działania, zamiast samemu linkować te frameworki.

Integracja z Windows jeszcze nie jest dostępna. Planowany projekt zakłada jedną binarkę w Ruście korzystającą z WinRT i interfejsu MAPI Outlooka.

## Model sieciowy

`mcp-os` nie ma stałego portu: startuje z `PORT=0`, system operacyjny wybiera wolny port, a menedżer procesów go zapisuje, żeby Hub mógł go odnaleźć. Na macOS nasłuchuje na `127.0.0.1`, a na Windows na adresie IP wirtualnego adaptera WSL, bo tam loopback w trybie mirrored nie działa. W odróżnieniu od workerów w kontenerach nigdy nie nasłuchuje na `0.0.0.0`.

## Bezpieczeństwo

Każde żądanie do `mcp-os` niesie token dostępu (bearer token) tworzony osobno dla każdej sesji przy jej starcie, dzięki czemu żaden inny proces na twojej maszynie nie sięgnie tego punktu końcowego. Szerszy obraz tego, do czego Claude ma dostęp, a do czego nie, znajdziesz na stronie [Jak obsługiwane są dane uwierzytelniające](/pl/docs/security/credentials/).

Cztery binarki macOS działają dodatkowo w trybie utwardzonego środowiska uruchomieniowego (Hardened Runtime) firmy Apple, które domyślnie ogranicza dostęp do API platformy: Apple Events dla `mail-cli` i `notes-cli`, a także kalendarze i EventKit dla `calendar-cli` oraz `reminders-cli`.

## Uprawnienia macOS (TCC)

Na macOS dostępu do Kalendarza, Przypomnień, Poczty i Notatek pilnuje TCC (Transparency, Consent and Control), czyli mechanizm stojący za oknami „zezwól na dostęp”. Uruchomiony pomocnik CLI musi przekazać dodatkowe informacje, żeby spełnić wymagania TCC tam, gdzie zwykłe polecenie po cichu by się nie powiodło. Jak każdy pomocnik się identyfikuje i jak Speedwave uzgadnia stan uprawnień przy starcie, opisuje strona [Uprawnienia systemowe (TCC) na macOS](/pl/docs/under-the-hood/os-integration-permissions/).