7.4 KiB
Moduł mcp
Read this in: English | 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 doraw/inbox/, ackb-ingestzamienia 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.yamli 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:
- 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. - 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_requiredz 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. - Pomyłki da się cofnąć.
withdraw_submissionusuwa oczekujące zgłoszenie;request_retractionkolejkuje przetworzone dlackb-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 (English).
Skill ckb-mcp prowadzi agenta przez te same kroki.
Zapis decyzji projektowych
- D-0001: dlaczego moduły są plikami w repozytorium.
- D-0007: 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.