# Moduł `mcp` *Read this in: [English](README.md) | **Polski*** Opcjonalny. Instalacja: „install the mcp module”; usunięcie: „uninstall the mcp module”. Instalacja dodaje skill `ckb-mcp` i blok routingu. Sam serwer działa w miejscu, z folderu `server/`, i nic nie robi, dopóki ktoś go nie uruchomi. ## Co robi Udostępnia tę bazę wiedzy przez Model Context Protocol. Może z niej wtedy korzystać każdy klient MCP: aplikacje Claude (web, desktop i mobile, jako własny konektor), Claude Code albo inny agent. | Narzędzie | Co robi | |---|---| | `kb_overview` | `ABOUT.md` (do czego służy ta KB, w słowach jej właściciela), indeks routingu, strona przeglądowa, informacja, które warstwy `linked/`/`libs/` istnieją, i liczba zgłoszeń czekających w skrzynce | | `search_kb` | Uszeregowani kandydaci z własnego skryptu fuzji `ckb-retrieve`: dokładny tekst, tldr, zakres projektu, graf, wiarygodność | | `read_page` | Jeden plik po ścieżce, z `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` oraz własne prośby wywołującego w `raw/retractions/` | | `list_pages` | Strony w katalogu, z tytułem, typem i tldr | | `add_to_inbox` | Zgłasza nowy materiał jako plik w `raw/inbox/`, z informacją o pochodzeniu, a potem go commituje i wypycha | | `list_my_submissions` | Twoje zgłoszenia: oczekujące w `raw/inbox/` albo przetworzone, razem ze stronami i krawędziami, które z nich powstały | | `withdraw_submission` | Usuwa jedno z twoich zgłoszeń, które jeszcze czeka | | `request_retraction` | Zapisuje w `raw/retractions/` prośbę o usunięcie jednego z twoich przetworzonych zgłoszeń i wszystkiego, co z niego powstało; wykonuje ją lokalnie `ckb-retract` | Dokument może usunąć lub zgłosić do usunięcia tylko osoba, która go dodała. Serwer porównuje wywołującego z polem `submitted_by` zgłoszenia, a `ckb-retract` sprawdza to ponownie, zanim cokolwiek zmieni. W sesji lokalnej opiekun bazy może pominąć to sprawdzenie po wpisaniu potwierdzenia, co trafia do logu jako obejście, więc źródło nie przetrwa utraty dostępu przez autora. Do tego zasób `ckb://rules` (`AGENTS.md`) i prompt `answer_from_kb`. Instrukcje serwera podają klientowi kolejność kaskady. Mówią też, żeby przed oparciem się na stronie sprawdzić ją ze źródłami i żeby zgłoszenie do skrzynki opisywać jako zakolejkowane, nigdy jako aktualizację wiki. ## Czego celowo nie robi - **Żadnych edycji wiki z zewnątrz.** Zdalny klient nie może tworzyć ani zmieniać stron w `wiki/`. Nowa wiedza trafia do `raw/inbox/`, a `ckb-ingest` zamienia ją na strony tutaj, z logiem, schematem, odnośnikami i przeglądem. Zdalne zapisy są małe (nowe pliki w skrzynce, wycofania własnych zgłoszeń, prośby o usunięcie), a do wiki nie trafia nic nieprzejrzanego. - **Żadnych prywatnych obszarów.** `workload/`, `tmp/`, `raw/saved-conversations/`, pliki ukryte, `*.local.yaml` i katalog główny repozytorium są niedostępne do odczytu. - **Żadnych połączeń na żywo.** Dla `libs/` serwer udostępnia wygenerowany indeks, tak jak kaskada. Nigdy sam nie łączy się z SharePointem ani Drive. ## Logowanie to jeden przełącznik Tryb wybiera `CKB_MCP_AUTH`. Poza nim nic się między trybami nie zmienia, a to samo wdrożenie można przełączyć restartem. | Tryb | Dla kogo | Jak uwierzytelnia się klient | |---|---|---| | `none` | stdio albo tylko loopback/VPN | — (serwer odmawia nasłuchu na publicznym adresie) | | `token` | jedna osoba, kilka osób, agenci | `https://host//mcp` (Claude web) albo `Authorization: Bearer` (klienci wysyłający nagłówki); token do odczytu i zapisu i/lub tylko do odczytu, albo plik z tokenem na osobę lub agenta, gdzie wpis ma tylko odczyt, o ile nie ma `write` | | `oauth` | zespół | OAuth 2.1 z twoim dostawcą tożsamości; serwer weryfikuje JWT przez JWKS (albo introspekcją tokenów nieprzezroczystych), z listami dostępu i zapisu po adresie e-mail lub `@domenie` oraz opcjonalnym zakresem zapisu dla klientów maszynowych | Wywołujący tylko do odczytu nigdy nie widzą narzędzi zapisu. W każdym trybie autorem zgłoszenia w git jest osoba, która je wysłała. Serwer commituje jako `ckb-mcp`. ## Kilka baz wiedzy Uruchom osobny serwer dla każdej bazy, każdy z własnym klonem, adresem, logowaniem i `CKB_MCP_NAME`. Klient taki jak claude.ai ma wtedy osobny konektor dla każdej bazy. Opis każdego narzędzia zaczyna się od `[]`, więc model wie, której bazy pyta. `server/compose.example.yaml` uruchamia dwie obok siebie. Gdy podłączonych jest kilka baz, prawdziwym ryzykiem jest zapis do złej bazy: materiał jednego klienta może trafić do bazy innego. Dlatego przy `CKB_MCP_CONFIRM=auto` (domyślnie) działają trzy zabezpieczenia: 1. **Cel jest nazwany.** Każdy zapis przyjmuje `kb`, które musi być równe nazwie tego serwera, inaczej nic nie zostaje zapisane. Zapis wysłany do złego konektora kończy się błędem, zamiast trafić na miejsce. 2. **Użytkownik potwierdza.** Klient obsługujący elicitation MCP pokazuje pytanie („Dodać »X« do bazy 'alpha'?”) we własnym interfejsie. W przeciwnym razie pierwsze wywołanie zwraca `confirmation_required` z pytaniem i podpisanym kodem. Model musi zapytać ciebie, a potem powtórzyć wywołanie z kodem. Kod jest związany z tą bazą, tym wywołującym i dokładnie tymi argumentami, i wygasa po 15 minutach. 3. **Pomyłki da się cofnąć.** `withdraw_submission` usuwa oczekujące zgłoszenie; `request_retraction` kolejkuje przetworzone dla `ckb-retract`, który usuwa źródło i dokładnie to, co wniosło. Ścieżka dwuetapowa zakłada, że model rzeczywiście cię zapyta. Jako bramkę, której model nie pominie, ustaw też narzędzia zapisu na *pytaj przed użyciem* w ustawieniach konektora w kliencie. Okno zgody pokazuje wtedy argument `kb`. Wycofanie naprawia bazę w obecnym stanie; **treść zostaje w historii gita** i w każdym klonie. Jeśli wyciekł poufny materiał, usunięcie go z historii to osobne, świadome przepisanie historii. `ckb-retract` to wyjaśnia, ale tego nie robi. ## Układ plików ``` server/ server.py połączenie z MCP: narzędzia, zasób, prompt, transporty kb.py polityka ścieżek, odczyt, wyszukiwanie, zapis do skrzynki, synchronizacja git (bez zależności od MCP) auth.py middleware tokenów i weryfikator tokenów OAuth requirements.txt mcp>=2.3,<3 (dociąga uvicorn, PyJWT, httpx2) Dockerfile tylko środowisko uruchomieniowe; przy pierwszym starcie klonuje bazę do wolumenu entrypoint.sh compose.example.yaml env.example wszystkie ustawienia, z komentarzami (po angielsku) tokens.example.json kształt pliku z tokenami na osobę ``` Konfiguracja, wdrożenie i podłączenie Claude krok po kroku: [docs/MCP.pl.md](../../../docs/MCP.pl.md) ([English](../../../docs/MCP.md)). Skill `ckb-mcp` prowadzi agenta przez te same kroki. ## Zapis decyzji projektowych - [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): dlaczego moduły są plikami w repozytorium. - [D-0007](../../../docs/decisions/0007-mcp-server-module.md): dlaczego zdalne zapisy ograniczają się do skrzynki i próśb o usunięcie, dlaczego tryby logowania przełącza jedna flaga i dlaczego serwer działa w miejscu. Rekordy decyzji są po angielsku. --- *Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../../../LICENSE).*