ckb/.agents/modules/mcp/README.pl.md
Michał Kopeć da2833abfe Sync: local changes as of 2026-11-01T20:31:36Z
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 21:31:36 +01:00

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 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 (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.