ckb/docs/MCP.pl.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

10 KiB

Korzystanie z tej bazy wiedzy w Claude i innych klientach MCP

Read this in: English | 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 (po angielsku), a układ plików modułu w jego README.


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:

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://<host>/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://<host>/<token>/mcp. Inni klienci wysyłają go jako Authorization: Bearer <token>. 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://<host>/<token>/mcp. W trybie OAuth wklej https://<host>/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://<host>/mcp --header "Authorization: Bearer <token>"

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.