# Korzystanie z tej bazy wiedzy w Claude i innych klientach MCP *Read this in: [English](MCP.md) | **Polski*** Opcjonalny moduł `mcp` udostępnia tę bazę wiedzy przez serwer MCP. Możesz wtedy przeszukiwać ją, czytać i dodawać do niej materiał z aplikacji Claude (web, desktop i mobile, jako własny konektor), z Claude Code albo z dowolnego innego agenta obsługującego MCP. Na urządzeniu, z którego korzystasz, nie potrzebujesz kopii repozytorium. Ten przewodnik jest dla osoby, która serwer konfiguruje i z niego korzysta. Uzasadnienie projektu znajdziesz w [D-0007](decisions/0007-mcp-server-module.md) (po angielsku), a układ plików modułu w [jego README](../.agents/modules/mcp/README.pl.md). --- ## Co może podłączony klient | Mówisz (w Claude) | Co się dzieje | |---|---| | „Co wiemy o polityce ponawiania w Atlasie?” | Claude przeszukuje bazę, czyta strony, na których się opiera, i odpowiada z podaniem ścieżek stron | | „Dodaj to do bazy: ...” | Materiał trafia do `raw/inbox/` jako nowy plik, z twoim imieniem i nazwiskiem, datą i źródłem. **Nie** jest jeszcze w wiki: zamienia go na strony najbliższy „Ingest” w sesji lokalnej | | „Pokaż moje zgłoszenia do tej bazy” | Pokazuje twoje zgłoszenia: oczekujące albo już przetworzone, razem ze stronami, które z nich powstały | | „Cofnij moje ostatnie zgłoszenie, to zła baza” | Wycofuje oczekujące zgłoszenie (plik zostaje usunięty) | | „Usuń to, co powstało z tej notatki, powinna trafić do innej bazy” | Dla zgłoszenia już przetworzonego: zapisuje prośbę w `raw/retractions/`. Najbliższa sesja lokalna wykonuje ją przez `ckb-retract`, po twojej akceptacji planu | Zdalny klient **nigdy nie edytuje `wiki/` bezpośrednio**. Ingest i wycofywanie zostają w sesjach lokalnych, gdzie obowiązują log, schemat stron i kroki przeglądu. Dokument może wycofać lub zgłosić do usunięcia tylko osoba, która go dodała. Opiekun bazy może jednak wycofać każde źródło w sesji lokalnej, po wpisaniu potwierdzenia, więc nic nie utknie, gdy autor odejdzie. --- ## 1. Zainstaluj moduł W sesji lokalnej powiedz **„install the mcp module”**. Instalacja dodaje skill `ckb-mcp` i zapisuje moduł w `ckb.yaml`. Sam serwer leży w `.agents/modules/mcp/server/` i nic nie robi, dopóki ktoś go nie uruchomi. Od tej chwili „help me deploy the MCP server” albo „connect the KB to Claude web” przeprowadzi cię przez resztę. Poniższe kroki opisują to samo. --- ## 2. Wybierz, gdzie działa serwer | Chcesz go używać w | Uruchom go | Uwagi | |---|---|---| | Claude Code lub Claude Desktop na tym komputerze | lokalnie, przez stdio | Nic nie trzeba hostować. Zgłoszenia to zwykłe pliki w twojej kopii roboczej | | Claude w przeglądarce lub na telefonie, albo dla zespołu | na serwerze z publicznym HTTPS | Aplikacja webowa Claude łączy się z chmury Anthropic, więc `localhost` ani adres dostępny tylko przez VPN nie zadziała | ### Lokalnie (stdio) Potrzebujesz Pythona 3.10 lub nowszego, a potem: ```bash pip install -r .agents/modules/mcp/server/requirements.txt claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \ python3 "$PWD/.agents/modules/mcp/server/server.py" ``` Autorem zgłoszeń jest twoje `git config user.name`/`user.email`. `ckb-sync-changes` commituje je jak każdą inną zmianę. ### Na serwerze (HTTPS) 1. **Daj serwerowi własny klon** z prawem do push. Nigdy nie wskazuj mu czyjejś kopii roboczej: przed każdym zapisem resetuje swój klon do stanu zdalnego i odmawia startu na klonie z lokalnymi zmianami. Użyj **klucza wdrożeniowego** SSH (deploy key) z prawem zapisu tylko do tego repozytorium. 2. **Skonfiguruj go.** Skopiuj `server/env.example` do `.env` i ustaw co najmniej `CKB_REPO_URL`, `CKB_MCP_PUBLIC_URL` i ustawienia logowania (krok 3). Ten plik opisuje każde ustawienie. 3. **Uruchom go** poleceniem `docker compose -f compose.example.yaml up -d --build` w folderze `server/` albo uruchom `server.py` pod systemd z tym samym środowiskiem. 4. **Postaw przed nim reverse proxy** (Caddy, Traefik, nginx) dla HTTPS. W trybie tokenów wyłącz log dostępu proxy dla tego hosta, bo token jest częścią adresu URL. 5. **Sprawdź go:** `https:///health` powinno odpowiedzieć `{"status":"ok",...}`. --- ## 3. Wybierz sposób logowania Decyduje jedno ustawienie, `CKB_MCP_AUTH`. Możesz je później zmienić i zrestartować serwer, nic innego nie trzeba ruszać. | Tryb | Dla kogo | Jak działa | |---|---|---| | `token` | tylko ty, kilka osób, agenci | Długi sekret. Aplikacja webowa Claude używa go w adresie: `https:////mcp`. Inni klienci wysyłają go jako `Authorization: Bearer `. Jeden token do odczytu i zapisu (`CKB_MCP_TOKEN`), jeden tylko do odczytu (`CKB_MCP_READ_TOKEN`) albo plik z tokenem dla każdej osoby lub agenta | | `oauth` | zespół | Logowanie przez twojego dostawcę tożsamości (Authentik, Keycloak, Zitadel, Auth0, Entra ID...). Ustalasz, kto może się łączyć i kto może zapisywać, po adresie e-mail albo `@domenie` | | `none` | tylko lokalne stdio | Serwer odmawia takiej pracy na publicznym adresie | **Dostęp tylko do odczytu.** - Przy tokenach: użyj `CKB_MCP_READ_TOKEN` albo pomiń `"write": true` dla danej osoby w pliku tokenów. - Przy OAuth: każdy spoza `CKB_MCP_OAUTH_WRITERS` ma tylko odczyt. Agenta bez adresu e-mail można ograniczyć do odczytu zakresem `CKB_MCP_OAUTH_WRITE_SCOPE`. - W obu przypadkach użytkownik tylko do odczytu w ogóle nie widzi narzędzi zapisu. Adres z tokenem traktuj jak hasło. Żeby go unieważnić, zmień token i zrestartuj serwer; stary adres przestanie działać. --- ## 4. Podłącz Claude - **Claude web/desktop/mobile:** Ustawienia → Konektory → *Dodaj własny konektor*. W trybie tokenów wklej `https:////mcp`. W trybie OAuth wklej `https:///mcp`; Claude sam znajdzie twojego dostawcę tożsamości. Jeśli dostawca nie obsługuje automatycznej rejestracji klienta, utwórz tam klienta i wpisz jego ID i sekret w *Ustawieniach zaawansowanych*. Adres przekierowania, który trzeba dopuścić, podaje dokumentacja konektorów Anthropic. - **Claude Code (zdalnie):** `claude mcp add --transport http ckb https:///mcp --header "Authorization: Bearer "` W planach Team i Enterprise właściciel organizacji może najpierw musieć dopuścić własne konektory. **Zalecane:** w ustawieniach konektora ustaw narzędzia zapisu (`add_to_inbox`, `withdraw_submission`, `request_retraction`) na *pytaj przed użyciem*. Wtedy nic nie zostanie zapisane bez twojej zgody w oknie samego Claude. --- ## 5. Kilka baz wiedzy w jednym Claude Uruchom **osobny serwer dla każdej bazy**, każdy z własnym klonem, adresem i ustawieniami dostępu, i dodaj każdy jako osobny konektor. `compose.example.yaml` pokazuje dwa obok siebie. Najprościej dać każdej bazie własną subdomenę (`kb-alpha.example.com`). Nadaj każdemu czytelną nazwę `CKB_MCP_NAME` i jednozdaniowy opis `CKB_MCP_DESCRIPTION`. Opis każdego narzędzia zaczyna się od tej nazwy, więc Claude wie, której bazy pyta. ### Jak serwer chroni przed zapisem do złej bazy 1. **Każdy zapis wskazuje swoją bazę.** Serwer odrzuca zapis, którego `kb` nie zgadza się z jego nazwą, więc materiał wysłany do złego konektora zostaje odrzucony, a nie zapisany. 2. **Każdy zapis potwierdzasz.** Jeśli klient to obsługuje, serwer pyta cię wprost: *„Dodać »Notatki z kickoffu« do bazy 'alpha'?”*. W przeciwnym razie Claude dostaje pytanie i kod potwierdzenia i musi zapytać ciebie, zanim powtórzy wywołanie z kodem. Kod działa tylko dla tej bazy, tej osoby i dokładnie tej treści, i wygasa po 15 minutach. 3. **Pomyłki da się cofnąć** (patrz następna sekcja). Kod potwierdzenia zakłada, że Claude rzeczywiście cię zapyta. Ustawienie *pytaj przed użyciem* z kroku 4 to jedyna bramka, której model nie może pominąć, więc używaj go zawsze, gdy podłączona jest więcej niż jedna baza. `CKB_MCP_CONFIRM=off` jest tylko dla bazy, która nigdy nie dzieli klienta z inną, albo dla zautomatyzowanego agenta. --- ## 6. Gdy coś trafiło do złej bazy 1. W konektorze tej bazy poproś Claude: *„Pokaż moje zgłoszenia do tej bazy.”* 2. **Jeszcze oczekuje** (nieprzetworzone): *„Wycofaj to.”* Plik zostaje usunięty. 3. **Już przetworzone:** *„Zgłoś usunięcie, to powinno być w project-beta.”* Prośba trafia wtedy do `raw/retractions/`. Widzi ją tylko konto, które ją złożyło. 4. Opiekun bazy uruchamia sesję lokalną. `ckb-ingest` i `ckb-lint` zgłaszają prośbę, a `ckb-retract` pokazuje dokładnie, co powstało ze źródła: strony do usunięcia, twierdzenia do wycięcia, krawędzie. Nic nie znika bez zgody opiekuna. Twierdzenia potwierdzone też przez inne źródło zostają. 5. Dodaj materiał do właściwej bazy przez jej własny konektor. **Czego wycofanie nie zrobi:** naprawia bazę tylko w jej obecnym stanie. Treść nadal jest w historii gita, w zdalnym repozytorium, w każdym klonie i w klonie serwera. Jeśli była poufna (materiał innego klienta, dane osobowe), usunięcie jej z historii to osobne, świadome przepisanie historii z force-pushem. `ckb-retract` to wyjaśnia, ale nigdy tego nie robi. --- ## Rozwiązywanie problemów | Objaw | Prawdopodobna przyczyna | |---|---| | Claude mówi, że nie może połączyć się z konektorem | Adres nie jest publicznym HTTPS albo proxy nie przekazuje `/mcp` (a przy OAuth także `/.well-known/oauth-protected-resource/...`) | | Każde żądanie dostaje `401` | Zły lub zmieniony token. W trybie OAuth sprawdź log serwera: zły adres JWKS albo niedostępny dostawca tożsamości są zapisywane jako `token verification failed` | | Claude może czytać, ale nie ma narzędzi zapisu | Twój token lub konto ma tylko odczyt albo ustawiono `CKB_MCP_WRITE=off` | | Zapis odrzucony komunikatem *This connector is the 'X' KB...* | Claude wybrał zły konektor. Nic nie zostało zapisane | | Serwer nie startuje: *CKB_MCP_GIT=sync resets ...* | Jego klon ma lokalne zmiany albo niewypchnięte commity. Daj mu czysty klon, używany tylko przez niego | | Zapisy zwracają *nothing was saved - please try again* | Zdalne repozytorium zmieniało się przez obie próby. Spróbuj ponownie; nic nie zostało zrobione do połowy | --- *Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../LICENSE).*