127 lines
7.4 KiB
Markdown
127 lines
7.4 KiB
Markdown
# Moduł `mcp`
|
|
|
|
*Read this in: [English](README.md) | **Polski***
|
|
|
|
Opcjonalny. Instalacja: „install the mcp module”; usunięcie: „uninstall the
|
|
mcp module”. Instalacja dodaje skill `ckb-mcp` i blok routingu. Sam serwer
|
|
działa w miejscu, z folderu `server/`, i nic nie robi, dopóki ktoś go nie
|
|
uruchomi.
|
|
|
|
## Co robi
|
|
|
|
Udostępnia tę bazę wiedzy przez Model Context Protocol. Może z niej wtedy
|
|
korzystać każdy klient MCP: aplikacje Claude (web, desktop i mobile, jako
|
|
własny konektor), Claude Code albo inny agent.
|
|
|
|
| Narzędzie | Co robi |
|
|
|---|---|
|
|
| `kb_overview` | `ABOUT.md` (do czego służy ta KB, w słowach jej właściciela), indeks routingu, strona przeglądowa, informacja, które warstwy `linked/`/`libs/` istnieją, i liczba zgłoszeń czekających w skrzynce |
|
|
| `search_kb` | Uszeregowani kandydaci z własnego skryptu fuzji `ckb-retrieve`: dokładny tekst, tldr, zakres projektu, graf, wiarygodność |
|
|
| `read_page` | Jeden plik po ścieżce, z `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` oraz własne prośby wywołującego w `raw/retractions/` |
|
|
| `list_pages` | Strony w katalogu, z tytułem, typem i tldr |
|
|
| `add_to_inbox` | Zgłasza nowy materiał jako plik w `raw/inbox/`, z informacją o pochodzeniu, a potem go commituje i wypycha |
|
|
| `list_my_submissions` | Twoje zgłoszenia: oczekujące w `raw/inbox/` albo przetworzone, razem ze stronami i krawędziami, które z nich powstały |
|
|
| `withdraw_submission` | Usuwa jedno z twoich zgłoszeń, które jeszcze czeka |
|
|
| `request_retraction` | Zapisuje w `raw/retractions/` prośbę o usunięcie jednego z twoich przetworzonych zgłoszeń i wszystkiego, co z niego powstało; wykonuje ją lokalnie `ckb-retract` |
|
|
|
|
Dokument może usunąć lub zgłosić do usunięcia tylko osoba, która go dodała.
|
|
Serwer porównuje wywołującego z polem `submitted_by` zgłoszenia, a
|
|
`ckb-retract` sprawdza to ponownie, zanim cokolwiek zmieni. W sesji lokalnej
|
|
opiekun bazy może pominąć to sprawdzenie po wpisaniu potwierdzenia, co trafia do
|
|
logu jako obejście, więc źródło nie przetrwa utraty dostępu przez autora.
|
|
|
|
Do tego zasób `ckb://rules` (`AGENTS.md`) i prompt `answer_from_kb`. Instrukcje
|
|
serwera podają klientowi kolejność kaskady. Mówią też, żeby przed oparciem się
|
|
na stronie sprawdzić ją ze źródłami i żeby zgłoszenie do skrzynki opisywać jako
|
|
zakolejkowane, nigdy jako aktualizację wiki.
|
|
|
|
## Czego celowo nie robi
|
|
|
|
- **Żadnych edycji wiki z zewnątrz.** Zdalny klient nie może tworzyć ani
|
|
zmieniać stron w `wiki/`. Nowa wiedza trafia do `raw/inbox/`, a `ckb-ingest`
|
|
zamienia ją na strony tutaj, z logiem, schematem, odnośnikami i przeglądem.
|
|
Zdalne zapisy są małe (nowe pliki w skrzynce, wycofania własnych zgłoszeń,
|
|
prośby o usunięcie), a do wiki nie trafia nic nieprzejrzanego.
|
|
- **Żadnych prywatnych obszarów.** `workload/`, `tmp/`,
|
|
`raw/saved-conversations/`, pliki ukryte, `*.local.yaml` i katalog główny
|
|
repozytorium są niedostępne do odczytu.
|
|
- **Żadnych połączeń na żywo.** Dla `libs/` serwer udostępnia wygenerowany
|
|
indeks, tak jak kaskada. Nigdy sam nie łączy się z SharePointem ani Drive.
|
|
|
|
## Logowanie to jeden przełącznik
|
|
|
|
Tryb wybiera `CKB_MCP_AUTH`. Poza nim nic się między trybami nie zmienia, a to
|
|
samo wdrożenie można przełączyć restartem.
|
|
|
|
| Tryb | Dla kogo | Jak uwierzytelnia się klient |
|
|
|---|---|---|
|
|
| `none` | stdio albo tylko loopback/VPN | — (serwer odmawia nasłuchu na publicznym adresie) |
|
|
| `token` | jedna osoba, kilka osób, agenci | `https://host/<token>/mcp` (Claude web) albo `Authorization: Bearer` (klienci wysyłający nagłówki); token do odczytu i zapisu i/lub tylko do odczytu, albo plik z tokenem na osobę lub agenta, gdzie wpis ma tylko odczyt, o ile nie ma `write` |
|
|
| `oauth` | zespół | OAuth 2.1 z twoim dostawcą tożsamości; serwer weryfikuje JWT przez JWKS (albo introspekcją tokenów nieprzezroczystych), z listami dostępu i zapisu po adresie e-mail lub `@domenie` oraz opcjonalnym zakresem zapisu dla klientów maszynowych |
|
|
|
|
Wywołujący tylko do odczytu nigdy nie widzą narzędzi zapisu. W każdym trybie
|
|
autorem zgłoszenia w git jest osoba, która je wysłała. Serwer commituje jako
|
|
`ckb-mcp`.
|
|
|
|
## Kilka baz wiedzy
|
|
|
|
Uruchom osobny serwer dla każdej bazy, każdy z własnym klonem, adresem, logowaniem i
|
|
`CKB_MCP_NAME`. Klient taki jak claude.ai ma wtedy osobny konektor dla każdej
|
|
bazy. Opis każdego narzędzia zaczyna się od `[<nazwa>]`, więc model wie, której
|
|
bazy pyta. `server/compose.example.yaml` uruchamia dwie obok siebie.
|
|
|
|
Gdy podłączonych jest kilka baz, prawdziwym ryzykiem jest zapis do złej bazy:
|
|
materiał jednego klienta może trafić do bazy innego. Dlatego przy
|
|
`CKB_MCP_CONFIRM=auto` (domyślnie) działają trzy zabezpieczenia:
|
|
|
|
1. **Cel jest nazwany.** Każdy zapis przyjmuje `kb`, które musi być równe
|
|
nazwie tego serwera, inaczej nic nie zostaje zapisane. Zapis wysłany do
|
|
złego konektora kończy się błędem, zamiast trafić na miejsce.
|
|
2. **Użytkownik potwierdza.** Klient obsługujący elicitation MCP pokazuje
|
|
pytanie („Dodać »X« do bazy 'alpha'?”) we własnym interfejsie. W przeciwnym
|
|
razie pierwsze wywołanie zwraca `confirmation_required` z pytaniem i
|
|
podpisanym kodem. Model musi zapytać ciebie, a potem powtórzyć wywołanie z
|
|
kodem. Kod jest związany z tą bazą, tym wywołującym i dokładnie tymi
|
|
argumentami, i wygasa po 15 minutach.
|
|
3. **Pomyłki da się cofnąć.** `withdraw_submission` usuwa oczekujące
|
|
zgłoszenie; `request_retraction` kolejkuje przetworzone dla `ckb-retract`,
|
|
który usuwa źródło i dokładnie to, co wniosło.
|
|
|
|
Ścieżka dwuetapowa zakłada, że model rzeczywiście cię zapyta. Jako bramkę,
|
|
której model nie pominie, ustaw też narzędzia zapisu na *pytaj przed użyciem*
|
|
w ustawieniach konektora w kliencie. Okno zgody pokazuje wtedy argument `kb`.
|
|
|
|
Wycofanie naprawia bazę w obecnym stanie; **treść zostaje w historii gita** i
|
|
w każdym klonie. Jeśli wyciekł poufny materiał, usunięcie go z historii to
|
|
osobne, świadome przepisanie historii. `ckb-retract` to wyjaśnia, ale tego nie
|
|
robi.
|
|
|
|
## Układ plików
|
|
|
|
```
|
|
server/
|
|
server.py połączenie z MCP: narzędzia, zasób, prompt, transporty
|
|
kb.py polityka ścieżek, odczyt, wyszukiwanie, zapis do skrzynki, synchronizacja git (bez zależności od MCP)
|
|
auth.py middleware tokenów i weryfikator tokenów OAuth
|
|
requirements.txt mcp>=2.3,<3 (dociąga uvicorn, PyJWT, httpx2)
|
|
Dockerfile tylko środowisko uruchomieniowe; przy pierwszym starcie klonuje bazę do wolumenu
|
|
entrypoint.sh
|
|
compose.example.yaml
|
|
env.example wszystkie ustawienia, z komentarzami (po angielsku)
|
|
tokens.example.json kształt pliku z tokenami na osobę
|
|
```
|
|
|
|
Konfiguracja, wdrożenie i podłączenie Claude krok po kroku:
|
|
[docs/MCP.pl.md](../../../docs/MCP.pl.md) ([English](../../../docs/MCP.md)).
|
|
Skill `ckb-mcp` prowadzi agenta przez te same kroki.
|
|
|
|
## Zapis decyzji projektowych
|
|
|
|
- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): dlaczego moduły są plikami w repozytorium.
|
|
- [D-0007](../../../docs/decisions/0007-mcp-server-module.md): dlaczego zdalne zapisy ograniczają się do skrzynki i próśb o usunięcie, dlaczego tryby logowania przełącza jedna flaga i dlaczego serwer działa w miejscu.
|
|
|
|
Rekordy decyzji są po angielsku.
|
|
|
|
---
|
|
|
|
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../../../LICENSE).*
|