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)
- 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.
- Skonfiguruj go. Skopiuj
server/env.exampledo.envi ustaw co najmniejCKB_REPO_URL,CKB_MCP_PUBLIC_URLi ustawienia logowania (krok 3). Ten plik opisuje każde ustawienie. - Uruchom go poleceniem
docker compose -f compose.example.yaml up -d --buildw folderzeserver/albo uruchomserver.pypod systemd z tym samym środowiskiem. - 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.
- Sprawdź go:
https://<host>/healthpowinno 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_TOKENalbo pomiń"write": truedla danej osoby w pliku tokenów. - Przy OAuth: każdy spoza
CKB_MCP_OAUTH_WRITERSma tylko odczyt. Agenta bez adresu e-mail można ograniczyć do odczytu zakresemCKB_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 wklejhttps://<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
- Każdy zapis wskazuje swoją bazę. Serwer odrzuca zapis, którego
kbnie zgadza się z jego nazwą, więc materiał wysłany do złego konektora zostaje odrzucony, a nie zapisany. - 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.
- 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
- W konektorze tej bazy poproś Claude: „Pokaż moje zgłoszenia do tej bazy.”
- Jeszcze oczekuje (nieprzetworzone): „Wycofaj to.” Plik zostaje usunięty.
- 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. - Opiekun bazy uruchamia sesję lokalną.
ckb-ingestickb-lintzgłaszają prośbę, ackb-retractpokazuje 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ą. - 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.