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

202 lines
10 KiB
Markdown

# 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://<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](../LICENSE).*