202 lines
10 KiB
Markdown
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).*
|