From bbfda5a65d8500bb97445c8f568910c4b10d3db3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Thu, 29 Oct 2026 14:50:12 +0100 Subject: [PATCH] Sync: local changes as of 2026-10-29T13:50:12Z Co-Authored-By: Claude Fable 5.1 --- .agents/modules/mcp/README.md | 121 +++++ .agents/modules/mcp/README.pl.md | 127 +++++ .../modules/mcp/fragments/agents-routing.md | 26 + .../modules/mcp/fragments/gitignore.snippet | 3 + .agents/modules/mcp/module.yaml | 40 ++ .agents/modules/mcp/server/Dockerfile | 15 + .agents/modules/mcp/server/auth.py | 254 +++++++++ .../modules/mcp/server/compose.example.yaml | 37 ++ .agents/modules/mcp/server/entrypoint.sh | 28 + .agents/modules/mcp/server/env.example | 100 ++++ .agents/modules/mcp/server/kb.py | 507 ++++++++++++++++++ .agents/modules/mcp/server/requirements.txt | 3 + .agents/modules/mcp/server/server.py | 453 ++++++++++++++++ .../modules/mcp/server/tokens.example.json | 5 + .agents/modules/mcp/skills/ckb-mcp/SKILL.md | 174 ++++++ .agents/modules/software/README.md | 30 +- .agents/modules/software/README.pl.md | 83 +++ .agents/skills/ckb-add-conversation/SKILL.md | 29 +- .agents/skills/ckb-decide/SKILL.md | 17 +- .agents/skills/ckb-document/SKILL.md | 155 ++++++ .agents/skills/ckb-export-okf/SKILL.md | 12 +- .agents/skills/ckb-export-starlight/SKILL.md | 12 +- .agents/skills/ckb-index-external/SKILL.md | 44 +- .agents/skills/ckb-ingest/SKILL.md | 14 +- .agents/skills/ckb-init/SKILL.md | 29 +- .agents/skills/ckb-lint/SKILL.md | 39 +- .../skills/ckb-lint/scripts/session_start.py | 229 ++++++++ .agents/skills/ckb-module/SKILL.md | 16 +- .agents/skills/ckb-onboard-me/SKILL.md | 11 +- .agents/skills/ckb-project-summary/SKILL.md | 11 +- .agents/skills/ckb-quiz/SKILL.md | 6 +- .agents/skills/ckb-reset/SKILL.md | 27 +- .agents/skills/ckb-retract/SKILL.md | 150 ++++++ .agents/skills/ckb-retrieve/SKILL.md | 39 +- .agents/skills/ckb-routine/SKILL.md | 13 +- .agents/skills/ckb-sync-changes/SKILL.md | 15 +- .agents/skills/ckb-teach-me/SKILL.md | 19 +- .agents/skills/ckb-upgrade/SKILL.md | 51 +- AGENTS.md | 123 ++--- README.md | 93 ++-- README.pl.md | 267 ++++----- VERSION | 2 +- docs/CHANGELOG.md | 6 +- docs/CHANGELOG.pl.md | 6 +- docs/MANUAL.md | 195 ++++--- docs/MANUAL.pl.md | 296 +++++----- docs/MCP.md | 192 +++++++ docs/MCP.pl.md | 202 +++++++ docs/OPENSPEC.md | 5 +- docs/OPENSPEC.pl.md | 20 +- docs/decisions/0007-mcp-server-module.md | 170 ++++++ docs/decisions/0008-document-templates.md | 73 +++ .../0009-session-start-in-one-call.md | 63 +++ docs/decisions/README.md | 3 + raw/retractions/.gitadd | 0 templates/README.md | 56 ++ templates/status-report.md | 35 ++ tests/mcp_policy.py | 278 ++++++++++ tests/smoke.sh | 8 + workload/2026-10-21_michal-kopec_summary.md | 35 -- workload/2026-10-29_summary.md | 3 - 61 files changed, 4320 insertions(+), 755 deletions(-) create mode 100644 .agents/modules/mcp/README.md create mode 100644 .agents/modules/mcp/README.pl.md create mode 100644 .agents/modules/mcp/fragments/agents-routing.md create mode 100644 .agents/modules/mcp/fragments/gitignore.snippet create mode 100644 .agents/modules/mcp/module.yaml create mode 100644 .agents/modules/mcp/server/Dockerfile create mode 100644 .agents/modules/mcp/server/auth.py create mode 100644 .agents/modules/mcp/server/compose.example.yaml create mode 100755 .agents/modules/mcp/server/entrypoint.sh create mode 100644 .agents/modules/mcp/server/env.example create mode 100644 .agents/modules/mcp/server/kb.py create mode 100644 .agents/modules/mcp/server/requirements.txt create mode 100644 .agents/modules/mcp/server/server.py create mode 100644 .agents/modules/mcp/server/tokens.example.json create mode 100644 .agents/modules/mcp/skills/ckb-mcp/SKILL.md create mode 100644 .agents/modules/software/README.pl.md create mode 100644 .agents/skills/ckb-document/SKILL.md create mode 100644 .agents/skills/ckb-lint/scripts/session_start.py create mode 100644 .agents/skills/ckb-retract/SKILL.md create mode 100644 docs/MCP.md create mode 100644 docs/MCP.pl.md create mode 100644 docs/decisions/0007-mcp-server-module.md create mode 100644 docs/decisions/0008-document-templates.md create mode 100644 docs/decisions/0009-session-start-in-one-call.md create mode 100644 raw/retractions/.gitadd create mode 100644 templates/README.md create mode 100644 templates/status-report.md create mode 100644 tests/mcp_policy.py delete mode 100644 workload/2026-10-21_michal-kopec_summary.md delete mode 100644 workload/2026-10-29_summary.md diff --git a/.agents/modules/mcp/README.md b/.agents/modules/mcp/README.md new file mode 100644 index 0000000..27f4a18 --- /dev/null +++ b/.agents/modules/mcp/README.md @@ -0,0 +1,121 @@ +# `mcp` module + +*Read this in: **English** | [Polski](README.pl.md)* + +Opt-in. Install with "install the mcp module"; remove with "uninstall the mcp +module". Installing adds the `ckb-mcp` skill and a routing block. The server +itself runs in place from `server/` and does nothing until someone starts it. + +## What it does + +It serves this knowledge base over the Model Context Protocol. Any MCP client +can then use it: Claude's web, desktop and mobile apps (as a custom +connector), Claude Code, or another agent. + +| Tool | Does | +|---|---| +| `kb_overview` | The routing index, the overview page, which `linked/`/`libs/` layers exist, and the inbox backlog | +| `search_kb` | Ranked candidates from `ckb-retrieve`'s own fusion script: exact text, tldr, project scope, graph, trust | +| `read_page` | One file by path, from `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/`, plus the caller's own requests in `raw/retractions/` | +| `list_pages` | Pages under a directory with title, type and tldr | +| `add_to_inbox` | Submits new material as a file in `raw/inbox/`, with provenance, then commits and pushes it | +| `list_my_submissions` | Your own submissions: pending in `raw/inbox/`, or ingested, with the pages and edges built from them | +| `withdraw_submission` | Deletes one of your own submissions that is still pending | +| `request_retraction` | Files a request in `raw/retractions/` to remove one of your own ingested submissions and everything built from it; `ckb-retract` carries it out locally | + +Only the person who added a document can delete it or ask for its removal. The +server compares the caller with the submission's `submitted_by`, and +`ckb-retract` checks the same again before it changes anything. In a local +session a maintainer may override that check with typed confirmation, logged +as an override, so a source never outlives its submitter's access. + +Plus the `ckb://rules` resource (`AGENTS.md`) and an `answer_from_kb` prompt. +The server's instructions tell the client the cascade order. They also say to +verify a page against its sources before relying on it, and to report an inbox +submission as queued, never as a wiki update. + +## What it deliberately does not do + +- **No wiki edits from outside.** A remote client cannot create or change + `wiki/` pages. New knowledge lands in `raw/inbox/`, and `ckb-ingest` turns it + into pages here, keeping the log, schema, cross-links and review. Remote + writes stay small (new inbox files, the submitter's own withdrawals, + retraction requests), and nothing unreviewed reaches the wiki. +- **No private areas.** `workload/`, `tmp/`, `raw/saved-conversations/`, + dotfiles, `*.local.yaml` and the repo root stay unreadable. +- **No live connectors.** For `libs/`, the server serves the generated index, as + the cascade does. It never calls SharePoint or Drive itself. + +## Auth is a flag + +`CKB_MCP_AUTH` selects the mode. Nothing else changes between modes, and the +same deployment can move from one to the next with a restart. + +| Mode | For | How a client authenticates | +|---|---|---| +| `none` | stdio, or loopback/VPN only | — (the server refuses a public bind) | +| `token` | one person, a few, agents | `https://host//mcp` (Claude web) or `Authorization: Bearer` (clients that send headers); a read-write and/or a read-only token, or a per-person/agent file where each entry is read-only unless marked `write` | +| `oauth` | a team | OAuth 2.1 against your IdP; the server verifies JWTs via JWKS (or introspects opaque tokens), with allow and writer lists by email or `@domain`, and an optional write scope for machine clients | + +Read-only callers never see the write tools. In every mode, a submission's git +author is the person who made it. The server commits as `ckb-mcp`. + +## Several knowledge bases + +Run one server per KB, each with its own clone, URL, auth and `CKB_MCP_NAME`. +A client such as claude.ai then holds one connector per KB. Every tool +description starts with `[]`, so the model knows which KB it is asking. +`server/compose.example.yaml` runs two side by side. + +Writing to the wrong KB is the real risk once several are connected, because it +can put one client's material in another client's KB. So with +`CKB_MCP_CONFIRM=auto` (the default) there are three checks: + +1. **The target is named.** Every write takes `kb`, which must equal this + server's name, or nothing is written. A write sent to the wrong connector + fails rather than landing. +2. **The user confirms.** A client that supports MCP elicitation shows the + question ("Add “X” to the 'alpha' knowledge base?") in its own UI. Otherwise + the first call returns `confirmation_required` with a question and a signed + code. The model must ask you, then repeat the call with the code. The code is + bound to this KB, this caller and these exact arguments, and expires after 15 + minutes. +3. **Mistakes can be undone.** `withdraw_submission` deletes a pending item; + `request_retraction` queues an ingested one for `ckb-retract`, which removes + the source and exactly what it contributed. + +The two-step path relies on the model actually asking you. For a gate a model +cannot skip, also set the write tools to *ask before use* in the client's +connector settings. The approval dialog then shows the `kb` argument. + +Retraction fixes the KB as it stands; **the content stays in git history** and +in every clone. If it leaked confidential material, removing it from history is +a separate, deliberate rewrite. `ckb-retract` explains it but does not do it. + +## Layout + +``` +server/ + server.py MCP wiring: tools, resource, prompt, transports + kb.py path policy, reads, search, inbox writes, git sync (no MCP dependency) + auth.py token middleware and OAuth token verifier + requirements.txt mcp>=2.3,<3 (brings uvicorn, PyJWT, httpx2) + Dockerfile runtime only; clones the KB into a volume on first start + entrypoint.sh + compose.example.yaml + env.example every setting, commented + tokens.example.json per-person token file shape +``` + +Setup, deployment and connecting Claude, step by step: +[docs/MCP.md](../../../docs/MCP.md) ([Polski](../../../docs/MCP.pl.md)). The `ckb-mcp` +skill walks an agent through the same steps. + +## Design record + +- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): why modules are files in the repo. +- [D-0007](../../../docs/decisions/0007-mcp-server-module.md): why remote writes are limited to the inbox and retraction requests, why the auth modes are switched by a flag, and why the server runs in place. + +--- + +*Licensed under the Apache License, Version 2.0 - see [LICENSE](../../../LICENSE).* diff --git a/.agents/modules/mcp/README.pl.md b/.agents/modules/mcp/README.pl.md new file mode 100644 index 0000000..f8c4937 --- /dev/null +++ b/.agents/modules/mcp/README.pl.md @@ -0,0 +1,127 @@ +# 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` | 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//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 `[]`, 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).* diff --git a/.agents/modules/mcp/fragments/agents-routing.md b/.agents/modules/mcp/fragments/agents-routing.md new file mode 100644 index 0000000..c928eac --- /dev/null +++ b/.agents/modules/mcp/fragments/agents-routing.md @@ -0,0 +1,26 @@ +## MODULE: mcp + +This KB can be served over MCP by `.agents/modules/mcp/server/` — to Claude's +web/desktop apps as a custom connector, or to any MCP client. + +- Remote clients **read** `wiki/`, `linked/`, `libs/`, `raw/inbox/`, + `raw/archive/`, `outputs/` (plus their own requests in `raw/retractions/`). + They **write only to `raw/inbox/`** (add, or withdraw their own pending item) + **and `raw/retractions/`** (request a removal). They never edit + `wiki/` — ingest, the log and review stay here. +- Inbox items from the server carry `via: mcp`, `submitted_by`, `submitted_at` + and `source` in frontmatter. `ckb-ingest` treats them like any inbox item, + credits `submitted_by` as the source's author, and treats them as unreviewed + claims: corroborate before raising `confidence`. +- The server's clone commits as `ckb-mcp` with the submitter as git author; + `ckb-sync-changes` pulls those commits like any other. +- Remote clients can withdraw their own pending inbox items, and can file + retraction requests for their own ingested sources in `raw/retractions/`. + Only the person who added a document may file them; a maintainer may override + in a local session with typed confirmation. Those are + requests, not changes: `ckb-retract` carries them out with the user, and + `ckb-ingest` flags any that are pending. + +| User intent | Skill | +|---|---| +| Run, deploy, configure, or connect the MCP server; switch its auth mode; add a user or token | `ckb-mcp` | diff --git a/.agents/modules/mcp/fragments/gitignore.snippet b/.agents/modules/mcp/fragments/gitignore.snippet new file mode 100644 index 0000000..a94eb8f --- /dev/null +++ b/.agents/modules/mcp/fragments/gitignore.snippet @@ -0,0 +1,3 @@ +# MCP server secrets: per-person token files are never committed (.env already is ignored). +tokens.json +.agents/modules/mcp/server/*.local.* diff --git a/.agents/modules/mcp/module.yaml b/.agents/modules/mcp/module.yaml new file mode 100644 index 0000000..0eec86d --- /dev/null +++ b/.agents/modules/mcp/module.yaml @@ -0,0 +1,40 @@ +# Cascade KB module manifest — read by `ckb-module` on install/uninstall. +# See docs/decisions/0007-mcp-server-module.md for the design. +name: mcp +title: MCP server (remote access from Claude and other MCP clients) +version: 1.0.0 +requires_kb_schema: "1.5" +summary: > + Serves this knowledge base over the Model Context Protocol, so Claude's web + and desktop apps (as a custom connector), Claude Code, or any MCP client can + search and read it, and submit new material to raw/inbox/ for the next ingest. + Auth is a flag: none, shared token(s), or OAuth via an external identity provider. + +# Skills copied into .agents/skills/ on install, removed on uninstall. +skills: + - ckb-mcp + +# The server runs from .agents/modules/mcp/server/ in place — no scaffold, so a +# template upgrade replaces the server together with the rest of the module. +scaffold: [] + +agents_fragment: fragments/agents-routing.md +gitignore_fragment: fragments/gitignore.snippet + +# No page schema additions. Inbox items carry provenance frontmatter +# (submitted_by, submitted_at, via, source), but raw/ is input, not wiki pages. +schema_additions: {} + +depends_on: + - name: python>=3.10 + scope: server-host-only + check: "python3 -c 'import sys; sys.exit(sys.version_info < (3, 10))'" + optional: true + note: > + Needed only on the machine that runs the server (the Dockerfile brings its + own). The KB itself and every other skill keep working without it. + - name: mcp (Python SDK) + scope: server-host-only + check: "python3 -c 'import mcp.server.mcpserver'" + optional: true + note: "pip install -r .agents/modules/mcp/server/requirements.txt" diff --git a/.agents/modules/mcp/server/Dockerfile b/.agents/modules/mcp/server/Dockerfile new file mode 100644 index 0000000..6285ef9 --- /dev/null +++ b/.agents/modules/mcp/server/Dockerfile @@ -0,0 +1,15 @@ +# Runtime image for the ckb MCP server. It carries no KB content: the KB is +# cloned into the /kb volume on first start (see entrypoint.sh). +FROM python:3.12-slim +RUN apt-get update \ + && apt-get install -y --no-install-recommends git ripgrep openssh-client ca-certificates \ + && rm -rf /var/lib/apt/lists/* +COPY requirements.txt /app/requirements.txt +RUN pip install --no-cache-dir -r /app/requirements.txt +COPY entrypoint.sh /app/entrypoint.sh +RUN useradd --create-home --uid 10001 ckb && mkdir /kb && chown ckb /kb +USER ckb +ENV CKB_ROOT=/kb CKB_MCP_HOST=0.0.0.0 CKB_MCP_PORT=8765 CKB_MCP_GIT=sync +EXPOSE 8765 +HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/health')" +ENTRYPOINT ["/app/entrypoint.sh"] diff --git a/.agents/modules/mcp/server/auth.py b/.agents/modules/mcp/server/auth.py new file mode 100644 index 0000000..3c0d069 --- /dev/null +++ b/.agents/modules/mcp/server/auth.py @@ -0,0 +1,254 @@ +"""Authentication for the ckb MCP server, switched by CKB_MCP_AUTH: + + none no check. Only for stdio or a server reachable from localhost/VPN alone. + token shared secret(s). Accepted as `Authorization: Bearer ` or as a + secret path prefix `//mcp` - Claude's web connector cannot send a + custom header, so the path form is how it authenticates without OAuth. + A read-write CKB_MCP_TOKEN and/or a read-only CKB_MCP_READ_TOKEN, or + one per person/agent with its own write bit (CKB_MCP_TOKENS_FILE). + oauth the server is an OAuth 2.1 resource server: it advertises an external + authorization server (Authentik, Keycloak, Zitadel, Auth0, ...) and + verifies the JWT access tokens that server issues against its JWKS, + or via RFC 7662 introspection for opaque tokens. + +Either way the caller ends up as a User with a write bit, read by caller(). +Token mode sets it in an ASGI middleware; OAuth mode derives it from the MCP +SDK's verified access token. Read-only callers neither see nor can call the +write tools. +""" +import contextvars +import hmac +import json +import logging +import os +from pathlib import Path + +log = logging.getLogger("ckb-mcp.auth") +_TOKEN_USER = contextvars.ContextVar("ckb_token_user", default=None) + + +def _min_len(token, what): + if len(token) < 24: + raise SystemExit(f"{what} is shorter than 24 characters " + "(generate one with: python3 -c 'import secrets; print(secrets.token_urlsafe(32))')") + + +# ----------------------------------------------------------------- token --- +def load_tokens(env): + """[{token, name, email, write}] from CKB_MCP_TOKENS_FILE, else from CKB_MCP_TOKEN + (read-write) and/or CKB_MCP_READ_TOKEN (read-only). In the file, `write` must be + stated as true: an entry without it is read-only.""" + path = env.get("CKB_MCP_TOKENS_FILE") + if path: + tokens = [] + for e in json.loads(Path(path).read_text(encoding="utf-8")): + _min_len(e.get("token", ""), f"token for {e.get('name', '?')}") + tokens.append({"token": e["token"], "name": e.get("name", "ckb-mcp user"), + "email": e.get("email", "ckb-mcp@localhost"), "write": e.get("write") is True}) + if not tokens: + raise SystemExit(f"{path} lists no tokens") + else: + name, email = env.get("CKB_MCP_AUTHOR_NAME", "ckb-mcp user"), env.get("CKB_MCP_AUTHOR_EMAIL", "ckb-mcp@localhost") + tokens = [] + if env.get("CKB_MCP_TOKEN"): + _min_len(env["CKB_MCP_TOKEN"], "CKB_MCP_TOKEN") + tokens.append({"token": env["CKB_MCP_TOKEN"], "name": name, "email": email, "write": True}) + if env.get("CKB_MCP_READ_TOKEN"): + _min_len(env["CKB_MCP_READ_TOKEN"], "CKB_MCP_READ_TOKEN") + tokens.append({"token": env["CKB_MCP_READ_TOKEN"], "name": f"{name} (read-only)", "email": email, "write": False}) + if not tokens: + raise SystemExit("CKB_MCP_AUTH=token needs CKB_MCP_TOKEN, CKB_MCP_READ_TOKEN or CKB_MCP_TOKENS_FILE") + if len({t["token"] for t in tokens}) != len(tokens): + raise SystemExit("two token entries share the same secret") + return tokens + + +class TokenAuthMiddleware: + def __init__(self, app, tokens, mcp_path="/mcp", open_paths=("/health",)): + self.app = app + self.tokens = tokens + self.mcp_path = mcp_path + self.open_paths = open_paths + + def _match(self, presented): + found = None + for t in self.tokens: # compare against every entry: no early exit, no timing hint + if hmac.compare_digest(presented.encode(), t["token"].encode()): + found = t + return found + + async def __call__(self, scope, receive, send): + if scope["type"] != "http": + return await self.app(scope, receive, send) + headers = scope.get("headers", []) + path = scope.get("path", "") + if path in self.open_paths: + return await self.app(scope, receive, send) + + user = None + auth = dict(headers).get(b"authorization", b"").decode("latin-1") + if auth.lower().startswith("bearer "): + user = self._match(auth[7:].strip()) + if user is None: + # Secret path form: //mcp -> /mcp + seg, _, rest = path.lstrip("/").partition("/") + if seg and "/" + rest == self.mcp_path: + user = self._match(seg) + if user: + path = self.mcp_path + if user is None: + await send({"type": "http.response.start", "status": 401, + "headers": [(b"content-type", b"application/json")]}) + await send({"type": "http.response.body", "body": b'{"error":"unauthorized"}'}) + return + # The MCP handler runs in a task spawned from this request, so it sees this value. + reset = _TOKEN_USER.set(user) + try: + return await self.app(dict(scope, path=path, raw_path=path.encode()), receive, send) + finally: + _TOKEN_USER.reset(reset) + + +def caller(mode, env): + """(name, email, may_write) for the current request, or None when unauthenticated.""" + if mode == "token": + u = _TOKEN_USER.get() + return (u["name"], u["email"], u["write"]) if u else None + if mode == "oauth": + from mcp.server.auth.middleware.auth_context import get_access_token + + tok = get_access_token() + if tok is None: + return None + claims = tok.claims or {} + sub = claims.get("sub") or tok.subject or "unknown" + name = claims.get("name") or claims.get("preferred_username") or sub + return name, claims.get("email") or f"{sub}@oauth.invalid", bool(claims.get("ckb_write")) + return env.get("CKB_MCP_AUTHOR_NAME", "ckb-mcp user"), env.get("CKB_MCP_AUTHOR_EMAIL", "ckb-mcp@localhost"), True + + +# ----------------------------------------------------------------- oauth --- +def oauth_settings(env, resource_url): + """AuthSettings + TokenVerifier for resource-server mode. Imports stay local so + none/token mode run without PyJWT installed.""" + from mcp.server.auth.settings import AuthSettings + + issuer = env.get("CKB_MCP_OAUTH_ISSUER") + if not issuer: + raise SystemExit("CKB_MCP_AUTH=oauth needs CKB_MCP_OAUTH_ISSUER (the authorization server URL)") + scopes = [s for s in env.get("CKB_MCP_OAUTH_SCOPES", "").split() if s] + settings = AuthSettings( + issuer_url=issuer, + resource_server_url=resource_url, + required_scopes=scopes or None, + # The verifier checks `aud` itself, so the SDK's resource check is off. + validate_token_resource=False, + ) + return settings, OAuthVerifier(env, resource_url) + + +def _split(v): + return [x.strip().lower() for x in (v or "").replace(",", " ").split() if x.strip()] + + +class OAuthVerifier: + def __init__(self, env, resource_url): + self.issuer = env["CKB_MCP_OAUTH_ISSUER"].rstrip("/") + self.audience = env.get("CKB_MCP_OAUTH_AUDIENCE") or resource_url + self.jwks_url = env.get("CKB_MCP_OAUTH_JWKS_URL") + self.introspection_url = env.get("CKB_MCP_OAUTH_INTROSPECTION_URL") + self.client_id = env.get("CKB_MCP_OAUTH_CLIENT_ID") + self.client_secret = env.get("CKB_MCP_OAUTH_CLIENT_SECRET") + # Introspection responses must name this server in `aud`, as JWTs must. Some IdPs + # omit `aud` from introspection; this opt-out accepts those, and only those. + self.allow_missing_aud = env.get("CKB_MCP_OAUTH_ALLOW_MISSING_AUD") == "1" + # Who may use the server at all, and who may write. An entry is an email, + # a subject, or "@domain". Empty allowed list = anyone the issuer authenticates. + self.allowed = _split(env.get("CKB_MCP_OAUTH_ALLOWED")) + self.writers = _split(env.get("CKB_MCP_OAUTH_WRITERS")) + # A token may write only if it also carries this scope, when set. This is how a + # machine client (client-credentials, no email) gets read-only or read-write. + self.write_scope = env.get("CKB_MCP_OAUTH_WRITE_SCOPE", "").strip() + if not (self.jwks_url or self.introspection_url): + raise SystemExit("CKB_MCP_AUTH=oauth needs CKB_MCP_OAUTH_JWKS_URL (JWT tokens) " + "or CKB_MCP_OAUTH_INTROSPECTION_URL (opaque tokens)") + self._jwks = None + + @staticmethod + def _matches(rules, claims): + email = (claims.get("email") or "").lower() + sub = (claims.get("sub") or "").lower() + for r in rules: + if r.startswith("@") and email.endswith(r): + return True + if r in (email, sub): + return True + return False + + def _claims_jwt(self, token): + import jwt + + if self._jwks is None: + self._jwks = jwt.PyJWKClient(self.jwks_url, cache_keys=True) + key = self._jwks.get_signing_key_from_jwt(token) + return jwt.decode(token, key.key, algorithms=["RS256", "ES256", "PS256", "EdDSA"], + audience=self.audience, issuer=self.issuer, + options={"require": ["exp", "iss", "sub"]}) + + async def _claims_introspect(self, token): + import httpx2 as httpx # the MCP SDK's own HTTP client; no extra dependency + + async with httpx.AsyncClient(timeout=10) as client: + r = await client.post(self.introspection_url, data={"token": token}, + auth=(self.client_id, self.client_secret) if self.client_id else None) + r.raise_for_status() + claims = r.json() + if not claims.get("active"): + return None + aud = claims.get("aud") + if not aud: + if not self.allow_missing_aud: + log.warning("introspected token has no aud; refused (CKB_MCP_OAUTH_ALLOW_MISSING_AUD=1 accepts it)") + return None + elif self.audience not in (aud if isinstance(aud, list) else [aud]): + return None + return claims + + async def verify_token(self, token): + from mcp.server.auth.provider import AccessToken + + import anyio + import jwt + + try: + if self.jwks_url: + # PyJWKClient fetches keys synchronously (first use, key rotation): keep it off the event loop. + claims = await anyio.to_thread.run_sync(self._claims_jwt, token) + else: + claims = await self._claims_introspect(token) + except jwt.InvalidTokenError as e: + # A bad, expired or foreign token: routine, and the client is told 401. + log.info("token rejected: %s", e) + return None + except Exception as e: + # JWKS unreachable, wrong URL, IdP down: an operator problem that would + # otherwise look like nothing but a stream of 401s. + log.warning("token verification failed: %s: %s", type(e).__name__, e) + return None + if not claims: + return None + if self.allowed and not self._matches(self.allowed, claims): + return None + scope = claims.get("scope") or claims.get("scp") or "" + scopes = scope.split() if isinstance(scope, str) else list(scope) + claims["ckb_write"] = (((not self.writers) or self._matches(self.writers, claims)) + and ((not self.write_scope) or self.write_scope in scopes)) + return AccessToken( + token=token, + client_id=str(claims.get("client_id") or claims.get("azp") or "unknown"), + scopes=scopes, + expires_at=claims.get("exp"), + resource=self.audience, + subject=claims.get("sub"), + claims=claims, + ) diff --git a/.agents/modules/mcp/server/compose.example.yaml b/.agents/modules/mcp/server/compose.example.yaml new file mode 100644 index 0000000..6492b34 --- /dev/null +++ b/.agents/modules/mcp/server/compose.example.yaml @@ -0,0 +1,37 @@ +# Copy next to your reverse proxy config, adjust, and `docker compose up -d`. +# The proxy terminates TLS and forwards each public hostname to its service. +# +# One service per knowledge base: each has its own clone, .env, auth and +# connector URL, so Claude can hold one connector per KB side by side. +# Add a KB by copying a service block with a new port, env file and volume. +x-ckb-mcp: &ckb-mcp + build: . + restart: unless-stopped + +services: + kb-alpha: + <<: *ckb-mcp + env_file: alpha.env # CKB_REPO_URL, CKB_MCP_PUBLIC_URL=https://kb-alpha.example.com, auth ... + ports: + - "127.0.0.1:8765:8765" # loopback only: the proxy is the public side + volumes: + - alpha:/kb # the server's own clone; it pulls and pushes + # Per-person/agent tokens: mount the file read-only and set CKB_MCP_TOKENS_FILE. + # - ./alpha-tokens.json:/run/secrets/ckb-tokens.json:ro + # Deploy key for an SSH CKB_REPO_URL (recommended over a token in the URL). + # The host file must exist: if it is missing, Docker mounts an empty directory + # instead (the entrypoint then stops and says so). Drop this line for an HTTPS URL. + - ./alpha_deploy_key:/run/secrets/ckb-deploy-key:ro + + kb-beta: + <<: *ckb-mcp + env_file: beta.env # CKB_MCP_PUBLIC_URL=https://kb-beta.example.com ... + ports: + - "127.0.0.1:8766:8765" + volumes: + - beta:/kb + - ./beta_deploy_key:/run/secrets/ckb-deploy-key:ro + +volumes: + alpha: + beta: diff --git a/.agents/modules/mcp/server/entrypoint.sh b/.agents/modules/mcp/server/entrypoint.sh new file mode 100755 index 0000000..92f6368 --- /dev/null +++ b/.agents/modules/mcp/server/entrypoint.sh @@ -0,0 +1,28 @@ +#!/bin/sh +# Container entrypoint: make sure /kb holds a clone of the KB, then serve it. +# The server code itself comes from the clone (.agents/modules/mcp/server/), so +# a template upgrade pulled into the KB upgrades the server with it. +set -eu +KB=${CKB_ROOT:-/kb} + +# SSH deploy key (recommended): mounted at /run/secrets/ckb-deploy-key. ssh refuses +# a key others can read and a host mount rarely has the right owner, so use a +# private copy. Unknown hosts are accepted on first contact and pinned after. +KEY=${CKB_SSH_KEY:-/run/secrets/ckb-deploy-key} +if [ -d "$KEY" ]; then + # Docker turns a bind mount of a missing host file into an empty directory. + echo "ckb-mcp: $KEY is a directory - the deploy key file to mount does not exist on the host" >&2 + exit 1 +fi +if [ -f "$KEY" ] && [ -z "${GIT_SSH_COMMAND:-}" ]; then + mkdir -p "$HOME/.ssh" && chmod 700 "$HOME/.ssh" + cp "$KEY" "$HOME/.ssh/deploy_key" && chmod 600 "$HOME/.ssh/deploy_key" + export GIT_SSH_COMMAND="ssh -i $HOME/.ssh/deploy_key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" +fi + +if [ ! -d "$KB/.git" ]; then + [ -n "${CKB_REPO_URL:-}" ] || { echo "ckb-mcp: $KB is not a clone and CKB_REPO_URL is unset" >&2; exit 1; } + git clone --quiet ${CKB_MCP_GIT_BRANCH:+--branch "$CKB_MCP_GIT_BRANCH"} "$CKB_REPO_URL" "$KB" +fi +git config --global --add safe.directory "$KB" +exec python "$KB/.agents/modules/mcp/server/server.py" diff --git a/.agents/modules/mcp/server/env.example b/.agents/modules/mcp/server/env.example new file mode 100644 index 0000000..f3fbf1a --- /dev/null +++ b/.agents/modules/mcp/server/env.example @@ -0,0 +1,100 @@ +# ckb MCP server configuration. Copy to .env next to compose.example.yaml. +# Docker env files do not strip inline comments: keep comments on their own lines. +# Every variable is optional unless marked REQUIRED for the mode you choose. + +# --- Where the KB comes from ------------------------------------------------ +# Clone URL, used once on first start. Recommended: an SSH URL plus a deploy key +# with write access to this one repo, mounted at /run/secrets/ckb-deploy-key +# (see compose.example.yaml). +CKB_REPO_URL=git@git.example.com:org/kb.git +# Alternative: an HTTPS URL with a token embedded +# (https://ckb-mcp:@git.example.com/org/kb.git). git stores that URL, token +# included, in plaintext in the clone's .git/config. The server never serves .git/, +# but anyone with a shell on the host or the volume can read it. +# (set by the image; for a bare-metal run, the KB root) +# CKB_ROOT=/kb +# (default: the clone's current branch) +# CKB_MCP_GIT_BRANCH=main +# CKB_MCP_GIT_REMOTE=origin + +# --- Identity: what clients call this KB ------------------------------------ +# One client (e.g. claude.ai) can hold several KB connectors. The name prefixes +# every tool description and the description tells the model what this KB covers. +# Defaults: the origin repo's name, and the tldr of wiki/overview.md. +# CKB_MCP_NAME=project-alpha +# CKB_MCP_DESCRIPTION=Alpha migration: architecture, decisions, people + +# --- Network ---------------------------------------------------------------- +# The public HTTPS address clients connect to, without the /mcp path. +# REQUIRED for oauth (it is the token audience and the metadata URL). +CKB_MCP_PUBLIC_URL=https://kb.example.com +# (set by the image) +# CKB_MCP_HOST=0.0.0.0 +# CKB_MCP_PORT=8765 +# CKB_MCP_PATH=/mcp +# (proxies whose X-Forwarded-* headers are trusted) +# CKB_MCP_TRUSTED_PROXIES=127.0.0.1 +# (enables Host-header (DNS rebinding) checks) +# CKB_MCP_ALLOWED_HOSTS=kb.example.com + +# --- Authentication: none | token | oauth ----------------------------------- +CKB_MCP_AUTH=token + +# token: shared secrets ... +# Claude web connector URL: https://kb.example.com//mcp +# Clients that send headers: https://kb.example.com/mcp + "Authorization: Bearer " +# Generate: python3 -c 'import secrets; print(secrets.token_urlsafe(32))' +# Read-write (search, read, add_to_inbox): +CKB_MCP_TOKEN= +# Read-only (no add_to_inbox; for agents and other tools). Either or both may be set. +# CKB_MCP_READ_TOKEN= +# git author of inbox submissions in single-token mode +CKB_MCP_AUTHOR_NAME=Your Name +CKB_MCP_AUTHOR_EMAIL=you@example.com +# ... or one token per person or agent, each with its own write bit +# (overrides both variables above; see tokens.example.json; no "write": true = read-only) +# CKB_MCP_TOKENS_FILE=/run/secrets/ckb-tokens.json + +# oauth: an external authorization server issues tokens; this server verifies them. +# (REQUIRED, exact `iss`) +# CKB_MCP_OAUTH_ISSUER=https://auth.example.com/application/o/ckb/ +# (JWT access tokens) +# CKB_MCP_OAUTH_JWKS_URL=https://auth.example.com/application/o/ckb/jwks/ +# (opaque tokens instead (RFC 7662) ...) +# CKB_MCP_OAUTH_INTROSPECTION_URL= +# (... with these credentials) +# CKB_MCP_OAUTH_CLIENT_ID= +# CKB_MCP_OAUTH_CLIENT_SECRET= +# (default: CKB_MCP_PUBLIC_URL + CKB_MCP_PATH) +# CKB_MCP_OAUTH_AUDIENCE= +# (space-separated scopes every token must carry) +# CKB_MCP_OAUTH_SCOPES= +# (introspection only: accept a response without `aud`; JWTs always need it) +# CKB_MCP_OAUTH_ALLOW_MISSING_AUD=1 +# Who may connect / who may write: emails, subjects, or @domain. Empty = everyone the issuer accepts. +# CKB_MCP_OAUTH_ALLOWED=@example.com +# CKB_MCP_OAUTH_WRITERS=you@example.com +# Writing also requires this scope in the token, when set. Lets a machine client +# (client credentials, no email) be read-only or read-write by the scopes it is granted. +# Users outside WRITERS, or without the scope, are read-only: write tools are hidden from them. +# CKB_MCP_OAUTH_WRITE_SCOPE=kb:write + +# --- Writes and git --------------------------------------------------------- +# inbox | off (read-only server) +CKB_MCP_WRITE=inbox +# Every write (add, withdraw, retraction request) names its target KB, and with +# auto the user confirms it: in the client's own dialog when the client supports +# elicitation, else by a second call carrying a signed, expiring code. Use off +# only for a KB that no client shares with another KB, or for an automated agent. +CKB_MCP_CONFIRM=auto +# Signs confirmation codes; random per process if unset. Set it (any long random +# string) when several replicas serve one KB. +# CKB_MCP_CONFIRM_SECRET= +# off | commit | sync (pull before reads, push after writes) +CKB_MCP_GIT=sync +# (seconds between pulls) +# CKB_MCP_PULL_INTERVAL=60 +# (committer; the submitter is the git author) +# CKB_MCP_GIT_NAME=ckb-mcp +# CKB_MCP_GIT_EMAIL=ckb-mcp@localhost +# CKB_MCP_MAX_INBOX_BYTES=200000 diff --git a/.agents/modules/mcp/server/kb.py b/.agents/modules/mcp/server/kb.py new file mode 100644 index 0000000..9f2910f --- /dev/null +++ b/.agents/modules/mcp/server/kb.py @@ -0,0 +1,507 @@ +"""Knowledge-base access for the ckb MCP server: path policy, reads, search, +inbox writes and git sync. + +No MCP dependency on purpose, so the policy that decides what a remote client +may read or write can be tested on its own (tests/mcp_policy.py). +""" +import json +import os +import re +import subprocess +import sys +import threading +import time +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path + +# What a remote client may read. Everything else - AGENTS.md aside, which is +# served as a resource - stays private: .git, .env, tmp/, workload/, and +# raw/saved-conversations/ (verbatim transcripts never leave the machine). +READ_PREFIXES = ("wiki/", "linked/", "libs/", "raw/inbox/", "raw/archive/", "raw/retractions/", "outputs/") +READ_ROOTS = tuple(p.rstrip("/") for p in READ_PREFIXES) +RETRIEVE = Path(".agents/skills/ckb-retrieve/scripts/retrieve_candidates.py") +MAX_LIST = 500 + + +class PolicyError(ValueError): + """A request the path or write policy refuses. The message is safe to show the client.""" + + +class UnsavedWork(RuntimeError): + """The sync-mode checkout holds work the server did not make, so it will not reset it.""" + + +@dataclass +class Author: + name: str + email: str + + def git(self): + return f"{self.name} <{self.email}>" + + +def parse_frontmatter(text): + """Flat key: value frontmatter, the same deliberately simple reading as the rest of the template.""" + if not text.startswith("---\n"): + return {}, text + end = text.find("\n---", 4) + if end < 0: + return {}, text + fm = {} + for line in text[4:end].splitlines(): + m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", line) + if m: + fm[m.group(1)] = m.group(2).strip().strip('"').strip("'") + return fm, text[end + 4:].lstrip("\n") + + +def slugify(s, limit=60): + s = re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-") + return (s[:limit].rstrip("-")) or "note" + + +class KB: + def __init__(self, root, git_mode="off", pull_interval=60, max_inbox_bytes=200_000, + committer=Author("ckb-mcp", "ckb-mcp@localhost"), remote="origin", branch=None): + self.root = Path(root).resolve() + if not (self.root / "wiki" / "index.md").is_file(): + raise SystemExit(f"{self.root} is not a Cascade KB root (no wiki/index.md)") + if git_mode not in ("off", "commit", "sync"): + raise SystemExit(f"CKB_MCP_GIT must be off, commit or sync, not {git_mode!r}") + self.git_mode = git_mode + self.pull_interval = pull_interval + self.max_inbox_bytes = max_inbox_bytes + self.committer = committer + self.remote = remote + self.branch = branch + self._last_pull = 0.0 + # One lock for every git operation and inbox write. Reentrant: a write holds it + # while forcing a pull; a read that finds it busy skips its pull instead of waiting. + self._lock = threading.RLock() + + # ------------------------------------------------------------- paths --- + def _allowed_dirs(self): + """Resolved directories a read may land in: the root, plus each linked/ target, + since linked/ entries are symlinks to other KB roots by design.""" + dirs = [self.root] + linked = self.root / "linked" + if linked.is_dir(): + dirs += [p.resolve() for p in linked.iterdir() if p.is_dir()] + return dirs + + def resolve_read(self, rel): + rel = (rel or "").strip().lstrip("/") + if not rel or "\x00" in rel: + raise PolicyError("empty path") + parts = Path(rel).parts + if ".." in parts: + raise PolicyError("'..' is not allowed in a path") + if any(p.startswith(".") for p in parts): + raise PolicyError("hidden files are not readable") + if parts[-1].endswith(".local.yaml"): + raise PolicyError("per-user local configuration is not readable") + if rel not in READ_ROOTS and not rel.startswith(READ_PREFIXES): + raise PolicyError(f"only {', '.join(READ_PREFIXES)} are readable") + # A linked/ is another KB's root: the same areas are readable inside it, + # not its workload/, tmp/ or root files. + if parts[0] == "linked" and len(parts) > 2: + inner = "/".join(parts[2:]) + if (inner not in READ_ROOTS and not inner.startswith(READ_PREFIXES) + or parts[2] == "linked" or inner.startswith("raw/retractions")): + raise PolicyError(f"inside linked// only {', '.join(p for p in READ_PREFIXES if p != 'linked/')} are readable") + # The checks above judge the path as written. A symlink would let an innocent + # name (wiki/x.md) land on .git/config, .env or workload/, so none is followed + # except linked/ itself, which is what linked/ exists for. With no other + # link on the way, the resolved path is the written one and the checks hold. + cur = self.root + for i, part in enumerate(parts): + cur = cur / part + if cur.is_symlink() and not (i == 1 and parts[0] == "linked"): + raise PolicyError("symbolic links are not served") + full = cur.resolve() + if not any(full == d or d in full.parents for d in self._allowed_dirs()): + raise PolicyError("path escapes the knowledge base") + return full + + def _may_see(self, rel, viewer): + """raw/retractions/ is private to each requester: a request's reason and page list + can say why material was confidential, or name another KB.""" + if not rel.startswith("raw/retractions/"): + return True + fm, _ = parse_frontmatter((self.root / rel).read_text(encoding="utf-8", errors="replace")) + m = re.search(r"<([^>]+)>", fm.get("requested_by", "")) + return bool(viewer and m and m.group(1).strip().lower() == viewer.email.lower()) + + def rel(self, full): + try: + return full.relative_to(self.root).as_posix() + except ValueError: + return full.as_posix() + + # ------------------------------------------------------------- reads --- + def read_page(self, rel, viewer=None): + self.maybe_pull() + full = self.resolve_read(rel) + if not full.is_file(): + raise PolicyError(f"no such file: {rel}") + if not self._may_see(self.rel(full), viewer): + raise PolicyError("retraction requests are readable only by the person who made them") + if full.stat().st_size > 2_000_000: + raise PolicyError("file larger than 2 MB; not served") + return full.read_text(encoding="utf-8", errors="replace") + + def list_pages(self, directory="wiki", viewer=None): + self.maybe_pull() + base = self.resolve_read(directory) + if not base.is_dir(): + raise PolicyError(f"not a directory: {directory}") + # rglob does not descend into symlinked directories, and every linked/ is + # one, so linked/ itself is walked one KB at a time from each link. + starts = sorted(p for p in base.iterdir() if p.is_dir()) if base == self.root / "linked" else [base] + out = [] + for f in sorted(f for s in starts for f in s.rglob("*.md")): + rel = f"{directory.strip('/')}/{f.relative_to(base).as_posix()}" + try: + self.resolve_read(rel) # same policy as read_page: skips links and hidden parts + except PolicyError: + continue + if not self._may_see(rel, viewer): + continue + fm, body = parse_frontmatter(f.read_text(encoding="utf-8", errors="replace")) + m = re.search(r"^#\s+(.+)$", body, re.M) + out.append({ + "path": rel, + "title": m.group(1).strip() if m else f.stem, + "type": fm.get("type"), "tldr": fm.get("tldr"), + }) + if len(out) >= MAX_LIST: + break + return out + + def overview(self): + self.maybe_pull() + parts = [] + for name in ("wiki/index.md", "wiki/overview.md"): + p = self.root / name + if p.is_file(): + parts.append(f"===== {name} =====\n{p.read_text(encoding='utf-8')}") + layers = [] + for layer in ("linked", "libs"): + d = self.root / layer + names = sorted(p.name for p in d.iterdir() if p.is_dir() and not p.name.startswith(".")) if d.is_dir() else [] + layers.append(f"{layer}/: {', '.join(names) if names else '(none)'}") + inbox = self.root / "raw" / "inbox" + pending = len([p for p in inbox.iterdir() if p.is_file() and not p.name.startswith(".")]) if inbox.is_dir() else 0 + layers.append(f"raw/inbox/: {pending} item(s) awaiting ingest") + retr = self.root / "raw" / "retractions" + n = len(list(retr.glob("*.md"))) if retr.is_dir() else 0 + layers.append(f"raw/retractions/: {n} retraction request(s) awaiting ckb-retract") + parts.append("===== cascade layers =====\n" + "\n".join(layers)) + return "\n\n".join(parts) + + def rules(self): + p = self.root / "AGENTS.md" + return p.read_text(encoding="utf-8") if p.is_file() else "" + + def search(self, query, top=10, scope=None): + self.maybe_pull() + script = self.root / RETRIEVE + if not script.is_file(): + raise PolicyError("retrieval script missing from this KB; run ckb-upgrade") + cmd = [sys.executable, str(script), query, "--root", str(self.root), "--json", "--top", str(int(top))] + if scope: + cmd += ["--scope", scope] + r = subprocess.run(cmd, capture_output=True, text=True, timeout=60) + if r.returncode != 0: + raise RuntimeError(f"retrieval failed: {r.stderr.strip()[-500:]}") + return json.loads(r.stdout) + + # ------------------------------------------------------------ writes --- + def add_to_inbox(self, title, content, author, source=None, now=None): + title = (title or "").strip() + if not title: + raise PolicyError("a title is required") + if not (content or "").strip(): + raise PolicyError("content is empty") + if len(content.encode("utf-8")) > self.max_inbox_bytes: + raise PolicyError(f"content larger than {self.max_inbox_bytes} bytes") + now = now or datetime.now(timezone.utc) + inbox = self.root / "raw" / "inbox" + + def apply(): + inbox.mkdir(parents=True, exist_ok=True) + stem = f"{now:%Y-%m-%d}_{slugify(title)}" + path, n = inbox / f"{stem}.md", 2 + while path.exists(): + path, n = inbox / f"{stem}-{n}.md", n + 1 + # Provenance lives in frontmatter so ckb-ingest can attribute the item; + # raw/ files are inputs, not wiki pages, so this is not the page schema. + header = [ + "---", + f"title: {json.dumps(title, ensure_ascii=False)}", + f"submitted_by: {json.dumps(author.git(), ensure_ascii=False)}", + f"submitted_at: {now.isoformat(timespec='seconds')}", + "via: mcp", + ] + if source: + header.append(f"source: {json.dumps(source.strip(), ensure_ascii=False)}") + header.append("---") + path.write_text("\n".join(header) + f"\n\n# {title}\n\n{content.rstrip()}\n", encoding="utf-8") + rel = self.rel(path) + return [rel], {"path": rel} + + return self._write(apply, f"Inbox via MCP: {title}", author) + + # ------------------------------------------------- submissions, undo --- + @staticmethod + def _submitter_email(fm): + m = re.search(r"<([^>]+)>", fm.get("submitted_by", "")) + return m.group(1).strip().lower() if m else None + + def _dependents(self, rel): + """Wiki pages and graph edges that cite a source path - what an ingest built from it.""" + pages, edges = [], 0 + wiki = self.root / "wiki" + for f in sorted(wiki.rglob("*.md")): + if f.is_symlink(): + continue + if rel in f.read_text(encoding="utf-8", errors="replace"): + pages.append(self.rel(f)) + ej = wiki / "graph" / "edges.json" + if ej.is_file(): + try: + edges = sum(1 for e in json.loads(ej.read_text(encoding="utf-8")).get("edges", []) + if rel in json.dumps(e)) + except ValueError: + pass + return {"pages": pages, "edges": edges} + + def submissions(self, author): + """The caller's own MCP submissions: pending in raw/inbox/, or ingested into + raw/archive/ together with what was built from them.""" + self.maybe_pull() + email = author.email.lower() + out = [] + for area, status in (("raw/inbox", "pending"), ("raw/archive", "ingested")): + base = self.root / area + if not base.is_dir(): + continue + for f in sorted(base.rglob("*.md")): + if f.is_symlink(): + continue + fm, _ = parse_frontmatter(f.read_text(encoding="utf-8", errors="replace")) + if fm.get("via") != "mcp" or self._submitter_email(fm) != email: + continue + item = {"path": self.rel(f), "title": fm.get("title"), "submitted_at": fm.get("submitted_at"), + "status": status} + if status == "ingested": + item.update(self._dependents(item["path"])) + item["retraction_requested"] = self._pending_retraction(item["path"]) is not None + out.append(item) + return out + + def _pending_retraction(self, target): + d = self.root / "raw" / "retractions" + for f in sorted(d.glob("*.md")) if d.is_dir() else []: + fm, _ = parse_frontmatter(f.read_text(encoding="utf-8", errors="replace")) + if fm.get("target") == target: + return self.rel(f) + return None + + def _inbox_item(self, rel, prefix): + full = self.resolve_read(rel) + if not self.rel(full).startswith(prefix) or not full.is_file(): + raise PolicyError(f"not a file under {prefix}: {rel}") + fm, _ = parse_frontmatter(full.read_text(encoding="utf-8", errors="replace")) + return full, fm + + def withdraw(self, rel, author): + """Delete a not-yet-ingested MCP submission from raw/inbox/. Only its submitter may.""" + def apply(): + # Runs on a checkout freshly reset to the remote, so "gone" means gone upstream. + try: + full, fm = self._inbox_item(rel, "raw/inbox/") + except PolicyError: + name = Path(rel).name + if rel.lstrip("/").startswith("raw/inbox/") and any((self.root / "raw" / "archive").glob(f"*/{name}")): + raise PolicyError("already ingested: it is in raw/archive/ now, so use request_retraction") + if rel.lstrip("/").startswith("raw/inbox/"): + raise PolicyError("no longer in raw/inbox/: already withdrawn, or moved by someone else") + raise + if fm.get("via") != "mcp" or self._submitter_email(fm) != author.email.lower(): + raise PolicyError("only the person who submitted this item can withdraw it") + full.unlink() + path = self.rel(full) + apply.title = fm.get("title", path) + return [path], {"withdrawn": path} + + return self._write(apply, lambda: f"Withdraw via MCP: {apply.title}", author) + + def request_retraction(self, rel, author, reason, now=None): + """Queue the removal of an ingested source and everything built from it. Only the + person who submitted the source may ask. The request is a file in raw/retractions/; + ckb-retract carries it out with a person, because unwinding wiki pages takes + judgement a remote client must not exercise.""" + reason = (reason or "").strip() + if not reason: + raise PolicyError("a reason is required (e.g. 'submitted to the wrong KB; belongs in project-beta')") + now = now or datetime.now(timezone.utc) + + def apply(): + full, fm = self._inbox_item(rel, "raw/archive/") + target = self.rel(full) + owner = self._submitter_email(fm) + if owner is None: + raise PolicyError("this source was not submitted through MCP, so it has no submitter who could " + "remove it; ask the KB's maintainers") + if owner != author.email.lower(): + raise PolicyError("only the person who submitted this source can ask for its removal") + existing = self._pending_retraction(target) + if existing: + return [], {"request": existing, "already_requested": True} + deps = self._dependents(target) + d = self.root / "raw" / "retractions" + d.mkdir(parents=True, exist_ok=True) + stem = f"{now:%Y-%m-%d}_{slugify(Path(target).stem)}" + path, n = d / f"{stem}.md", 2 + while path.exists(): + path, n = d / f"{stem}-{n}.md", n + 1 + lines = [ + "---", + "type: retraction-request", + f"target: {target}", + f"requested_by: {json.dumps(author.git(), ensure_ascii=False)}", + f"requested_at: {now.isoformat(timespec='seconds')}", + f"reason: {json.dumps(reason, ensure_ascii=False)}", + "via: mcp", + "---", "", + f"# Retract `{target}`", "", + reason, "", + "Cited at request time by:", "", + *([f"- `{p}`" for p in deps["pages"]] or ["- (no wiki page)"]), + f"- {deps['edges']} graph edge(s)", "", + ] + path.write_text("\n".join(lines), encoding="utf-8") + apply.target = target + return [self.rel(path)], {"request": self.rel(path), "target": target, **deps} + + return self._write(apply, lambda: f"Retraction request via MCP: {apply.target}", author) + + # --------------------------------------------------------------- git --- + def _git(self, *args, check=True): + # Every call carries the committer identity: a container has no global git + # identity to fall back on. + ident = ["-c", f"user.name={self.committer.name}", "-c", f"user.email={self.committer.email}"] + try: + r = subprocess.run(["git", "-C", str(self.root), *ident, *args], capture_output=True, text=True, timeout=120) + except subprocess.TimeoutExpired: + raise RuntimeError(f"git {args[0]} timed out after 120 s") from None + if check and r.returncode != 0: + raise RuntimeError(f"git {args[0]} failed: {(r.stderr or r.stdout).strip()[-500:]}") + return r + + def maybe_pull(self, force=False): + """Bring the checkout up to the remote at most once per pull_interval. A failure is + logged and the stale checkout keeps serving: reads must not go down with the remote.""" + if self.git_mode != "sync": + return + if not force and time.monotonic() - self._last_pull < self.pull_interval: + return + if not self._lock.acquire(blocking=force): + return # a write or another pull is running; serve the current checkout + try: + self._reset_to_remote() + except RuntimeError as e: + print(f"ckb-mcp: {e}; serving the current checkout", file=sys.stderr) + finally: + self._lock.release() + + def _tracking(self): + branch = self.branch or self._git("rev-parse", "--abbrev-ref", "HEAD").stdout.strip() + return branch, f"{self.remote}/{branch}" + + def _unsaved_work(self, ref): + """What a reset to ref would destroy that the server did not put there: local + changes or unpushed commits. None when the checkout holds nothing of the kind.""" + if self._git("status", "--porcelain").stdout.strip(): + return "local changes" + ahead = self._git("rev-list", "--count", f"{ref}..HEAD").stdout.strip() + return None if ahead == "0" else f"{ahead} unpushed commit(s)" + + def _reset_to_remote(self, own=False): + """Make the checkout exactly the remote branch. In sync mode the server's clone holds + nothing but writes it has already pushed, so this loses nothing - and it means a + rejected or conflicting write can never leave the clone diverged. That holds only + while nobody else works in the clone, so unless the leftovers are the server's own + (own=True: a write it just failed), any local work stops the reset instead.""" + self._last_pull = time.monotonic() + branch, ref = self._tracking() + self._git("fetch", "--quiet", self.remote, branch) + if not own: + found = self._unsaved_work(ref) + if found: + raise UnsavedWork(f"{self.root} has {found} that the server did not make; not resetting it " + f"to {ref}. Give the server its own clone, or push / discard those changes") + self._git("reset", "--hard", "--quiet", ref) + self._git("clean", "-fdq", "--", "raw") # files a failed write may have left; never ignored ones + + def _discard_own(self): + try: + self._reset_to_remote(own=True) + except RuntimeError: + pass + + def check_dedicated_clone(self): + """sync mode resets this checkout to the remote, so refuse a checkout holding + anything that a reset would destroy. The server must have its own clone. Runs at + startup, so every failure is one line naming the cause, never a traceback.""" + if self.git_mode != "sync": + return + try: + branch, ref = self._tracking() + self._git("fetch", "--quiet", self.remote, branch) + found = self._unsaved_work(ref) + except RuntimeError as e: + raise SystemExit(f"CKB_MCP_GIT=sync could not reach {self.remote} from {self.root}: {e}") from None + if found: + raise SystemExit(f"CKB_MCP_GIT=sync resets {self.root} to {ref} before every write, and this " + f"checkout has {found}. " + "Give the server its own clone (or push / discard those changes first).") + + def _write(self, apply, message, author): + """One write: in sync mode reset to the remote, apply, commit, push; a rejected push + is retried once from a fresh reset, and a second rejection resets again and reports + that nothing was saved. A checkout holding someone else's work is never reset: the + write is refused instead, and reads keep serving it as it is. apply() returns (paths, result) and raises PolicyError to + refuse; it re-runs on a retry, so its checks always see the current remote state.""" + with self._lock: + for attempt in (1, 2): + if self.git_mode == "sync": + try: + # A retry starts from the server's own rejected commit, so only the + # first reset checks for someone else's work. + self._reset_to_remote(own=attempt == 2) + except UnsavedWork as e: + print(f"ckb-mcp: {e}; refusing the write", file=sys.stderr) + raise PolicyError("the server's checkout holds changes it did not make, so it is not " + "accepting writes until its operator clears them; nothing was saved") from None + try: + paths, result = apply() + if not paths or self.git_mode == "off": + return {**result, "committed": False, "pushed": False} + msg = message() if callable(message) else message + self._git("add", "-A", "--", *paths) # -A: a withdrawal stages a deletion + self._git("commit", "--quiet", f"--author={author.git()}", "-m", msg, "--", *paths) + commit = self._git("rev-parse", "--short", "HEAD").stdout.strip() + if self.git_mode == "commit": + return {**result, "committed": True, "commit": commit, "pushed": False} + branch, _ = self._tracking() + if self._git("push", "--quiet", self.remote, f"HEAD:{branch}", check=False).returncode == 0: + return {**result, "committed": True, "commit": commit, "pushed": True} + except Exception: + if self.git_mode == "sync": + self._discard_own() # whatever this write left is the server's own + raise + self._discard_own() + raise PolicyError("the remote kept changing while saving; nothing was saved - please try again") diff --git a/.agents/modules/mcp/server/requirements.txt b/.agents/modules/mcp/server/requirements.txt new file mode 100644 index 0000000..630f541 --- /dev/null +++ b/.agents/modules/mcp/server/requirements.txt @@ -0,0 +1,3 @@ +# Runtime for the ckb MCP server. The SDK brings uvicorn, starlette, httpx2 and +# pyjwt[crypto], which cover the HTTP transport and OAuth token verification. +mcp>=2.3,<3 diff --git a/.agents/modules/mcp/server/server.py b/.agents/modules/mcp/server/server.py new file mode 100644 index 0000000..4d06e6f --- /dev/null +++ b/.agents/modules/mcp/server/server.py @@ -0,0 +1,453 @@ +#!/usr/bin/env python3 +"""ckb MCP server: exposes a Cascade KB to any MCP client - Claude's web and +desktop apps, Claude Code, or anything else that speaks MCP. + + python3 server.py # streamable HTTP on CKB_MCP_HOST:CKB_MCP_PORT + CKB_MCP_TRANSPORT=stdio python3 server.py + +Configuration is environment-only; env.example lists every variable. Reads are +cascade-aware (the ckb-retrieve script ranks, read_page serves the evidence). +Writes never touch wiki/: add_to_inbox drops material into raw/inbox/ for the +next ckb-ingest, withdraw_submission deletes one's own un-ingested item, and +request_retraction queues the removal of an ingested source for ckb-retract. +Every write names its target KB and is confirmed by the user (see _gate), because +one client may hold several KB connectors and a misrouted write is a leak. +""" +import hashlib +import hmac +import inspect +import json +import os +import secrets +import time +import re +import subprocess +import sys +from pathlib import Path + +HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) + +from kb import KB, Author, PolicyError # noqa: E402 +import auth # noqa: E402 + +from typing import Annotated # noqa: E402 + +from pydantic import BaseModel, Field # noqa: E402 + +from mcp.server.elicitation import AcceptedElicitation, ElicitationResult # noqa: E402 +from mcp.server.mcpserver import Context, Elicit, MCPServer, Resolve # noqa: E402 +from mcp.server.mcpserver.exceptions import ToolError # noqa: E402 +from mcp.types import ToolAnnotations # noqa: E402 + +ENV = os.environ +TRANSPORT = ENV.get("CKB_MCP_TRANSPORT", "http") +AUTH = ENV.get("CKB_MCP_AUTH", "none" if TRANSPORT == "stdio" else "token") +WRITE = ENV.get("CKB_MCP_WRITE", "inbox") +HOST = ENV.get("CKB_MCP_HOST", "127.0.0.1") +PORT = int(ENV.get("CKB_MCP_PORT", "8765")) +MCP_PATH = "/" + ENV.get("CKB_MCP_PATH", "/mcp").strip("/") +PUBLIC_URL = ENV.get("CKB_MCP_PUBLIC_URL", f"http://{HOST}:{PORT}").rstrip("/") + +if AUTH not in ("none", "token", "oauth"): + raise SystemExit(f"CKB_MCP_AUTH must be none, token or oauth, not {AUTH!r}") +if WRITE not in ("inbox", "off"): + raise SystemExit(f"CKB_MCP_WRITE must be inbox or off, not {WRITE!r}") +# auto: the user confirms every write - in the client's own dialog when it supports +# elicitation, else by a second call carrying a signed confirmation code. off: no +# confirmation (one KB, or an automated agent), the kb argument is still checked. +CONFIRM = ENV.get("CKB_MCP_CONFIRM", "auto") +if CONFIRM not in ("auto", "off"): + raise SystemExit(f"CKB_MCP_CONFIRM must be auto or off, not {CONFIRM!r}") +# Signs confirmation codes. Random per process unless set; set it when running +# several replicas of one KB, so a code issued by one is accepted by another. +_CONFIRM_KEY = (ENV.get("CKB_MCP_CONFIRM_SECRET") or secrets.token_hex(32)).encode() +CONFIRM_TTL = 900 +if (TRANSPORT == "http" and AUTH == "none" and HOST not in ("127.0.0.1", "localhost", "::1") + and ENV.get("CKB_MCP_ALLOW_UNAUTHENTICATED") != "1"): + raise SystemExit("Refusing to serve without authentication on a non-loopback address. " + "Set CKB_MCP_AUTH=token or oauth, or CKB_MCP_ALLOW_UNAUTHENTICATED=1 behind a VPN.") + +kb_store = KB( + ENV.get("CKB_ROOT", str(HERE.parents[3])), + git_mode=ENV.get("CKB_MCP_GIT", "off"), + pull_interval=int(ENV.get("CKB_MCP_PULL_INTERVAL", "60")), + max_inbox_bytes=int(ENV.get("CKB_MCP_MAX_INBOX_BYTES", "200000")), + committer=Author(ENV.get("CKB_MCP_GIT_NAME", "ckb-mcp"), ENV.get("CKB_MCP_GIT_EMAIL", "ckb-mcp@localhost")), + remote=ENV.get("CKB_MCP_GIT_REMOTE", "origin"), + branch=ENV.get("CKB_MCP_GIT_BRANCH") or None, +) + + +kb_store.check_dedicated_clone() + +# Author of submissions when no per-user identity exists (none mode, single token): +# the env vars, else this checkout's git identity, as Rule E resolves a session's author. +for _var, _key in (("CKB_MCP_AUTHOR_NAME", "user.name"), ("CKB_MCP_AUTHOR_EMAIL", "user.email")): + if not ENV.get(_var): + _r = subprocess.run(["git", "-C", str(kb_store.root), "config", _key], capture_output=True, text=True) + if _r.returncode == 0 and _r.stdout.strip(): + ENV[_var] = _r.stdout.strip() + + +def _kb_identity(): + """(name, description) telling this KB apart when one client connects to several. + Name: CKB_MCP_NAME, else the origin repo's name, else the folder name. + Description: CKB_MCP_DESCRIPTION, else wiki/overview.md's tldr.""" + name = ENV.get("CKB_MCP_NAME") + if not name: + r = subprocess.run(["git", "-C", str(kb_store.root), "remote", "get-url", "origin"], capture_output=True, text=True) + name = Path(r.stdout.strip()).name.removesuffix(".git") if r.returncode == 0 and r.stdout.strip() else kb_store.root.name + desc = ENV.get("CKB_MCP_DESCRIPTION", "") + ov = kb_store.root / "wiki" / "overview.md" + if not desc and ov.is_file(): + m = re.search(r"^tldr:\s*(.+)$", ov.read_text(encoding="utf-8").split("\n---", 1)[0], re.M) + desc = m.group(1).strip().strip('"') if m else "" + return re.sub(r"[^A-Za-z0-9_-]+", "-", name).strip("-") or "ckb", desc + + +KB_NAME, KB_DESC = _kb_identity() +ABOUT = f"the '{KB_NAME}' knowledge base" + (f" ({KB_DESC})" if KB_DESC else "") + +INSTRUCTIONS = f"""\ +This server is {ABOUT}: a Cascade Knowledge Base, a curated wiki (wiki/) +layered over read-only upstream KBs (linked/) and indexed external sources +(libs/). Other connectors may serve other knowledge bases. Use this one for +questions about '{KB_NAME}', and name the KB when you cite it. + +Answering: +- Start with search_kb; for orientation call kb_overview once. +- Cascade priority, first match wins: wiki/ > linked// > libs//. +- A search hit's tldr is compressed. Before relying on a page, read_page it, and + when it matters, read the sources it cites under raw/archive/ or outputs/. +- Cite page paths in answers. Flag pages marked stale or superseded_by, and + results from raw/inbox/ (submitted but not yet ingested, so unreviewed). +- If nothing answers the question, say so plainly rather than guessing. + +Adding knowledge: +- add_to_inbox stores new material in raw/inbox/. It is NOT in the wiki until + someone runs the ingest workflow, so tell the user it was queued, never that + the wiki was updated. Put the facts in content, with dates, names and where + they came from; one topic per submission. + +Writing safely when several KBs are connected: +- Every write takes kb='{KB_NAME}'. Pass it only when the user means this KB. + If the material could belong to more than one connected KB, ask which one + first; never pick by guess. +- A write may come back as confirmation_required. Ask the user the question it + gives, and call again with the confirmation code only after they say yes. + Never confirm on their behalf. +- Wrong KB? list_my_submissions shows what you sent here. Still pending: + withdraw_submission deletes it. Already ingested: request_retraction queues + its removal, with everything built from it, for the maintainers. Then submit + it again through the right KB's connector. +""" + +auth_settings, verifier = (None, None) +if AUTH == "oauth": + auth_settings, verifier = auth.oauth_settings(ENV, PUBLIC_URL + MCP_PATH) + +class KBServer(MCPServer): + async def list_tools(self): + """Read-only callers do not see write tools at all, so a model never offers + an action the server would refuse. call-time checks stay the real guard.""" + tools = await super().list_tools() + if WRITE_TOOLS and not _caller()[1]: + tools = [t for t in tools if t.name not in WRITE_TOOLS] + return tools + + +WRITE_TOOLS = set() + +mcp = KBServer( + name=KB_NAME, + title=f"{KB_NAME} (Cascade KB)", + instructions=INSTRUCTIONS, + version=(kb_store.root / "VERSION").read_text().strip() if (kb_store.root / "VERSION").is_file() else "", + auth=auth_settings, + token_verifier=verifier, +) + +READ = ToolAnnotations(read_only_hint=True, open_world_hint=False) + + +def _d(text): + """Tool description prefixed with the KB name, so a client holding several KB + connectors can tell their identically named tools apart.""" + return f"[{KB_NAME}] " + inspect.cleandoc(text) + + +def _caller(): + """(Author, may_write) for the current request; (None, False) if unauthenticated.""" + who = auth.caller(AUTH, ENV) + if who is None: + return None, False + name, email, may_write = who + return Author(name, email), may_write and WRITE != "off" + + +def _run(fn, *a, **kw): + try: + return fn(*a, **kw) + except PolicyError as e: + raise ToolError(str(e)) from e + + +@mcp.tool(annotations=READ, description=_d("""Orientation: the KB's routing index, its overview page, which upstream + layers (linked/, libs/) exist, and how many inbox items await ingest. + Call once at the start of a conversation about this KB.""")) +def kb_overview() -> str: + return f"Knowledge base: {ABOUT}\n\n" + _run(kb_store.overview) + + +@mcp.tool(annotations=READ, description=_d("""Ranked candidate pages for a question, fused from exact-text, title/tldr, + project-scope, graph and trust signals, across wiki/, linked/ and libs/. + Each candidate has path, title, type, tldr, staleness, confidence and the + sources it cites. `scope` narrows to a wiki/projects/.md project. + This ranks; it does not verify - read_page the candidates you rely on.""")) +def search_kb(query: str, top: int = 10, scope: str | None = None) -> dict: + return _run(kb_store.search, query, top=max(1, min(top, 30)), scope=scope) + + +@mcp.tool(annotations=READ, description=_d("""Full text of one file, by KB-root-relative path (e.g. wiki/entities/foo.md, + or a cited source such as raw/archive/2026-09-01/notes.md). Readable areas: + wiki/, linked/, libs/, raw/inbox/, raw/archive/, outputs/, and your own + retraction requests in raw/retractions/.""")) +def read_page(path: str) -> str: + return _run(kb_store.read_page, path, viewer=_caller()[0]) + + +@mcp.tool(annotations=READ, description=_d("""Markdown pages under a directory (recursive) with title, type and tldr. + Use for browsing, e.g. 'wiki/entities' or 'wiki/decisions'; prefer + search_kb for questions.""")) +def list_pages(directory: str = "wiki") -> list[dict]: + return _run(kb_store.list_pages, directory, viewer=_caller()[0]) + + +# ------------------------------------------------------------- write gate --- +class Confirm(BaseModel): + confirm: bool = Field(description=f"Yes - do this in the '{KB_NAME}' knowledge base") + + +def _kb_matches(kb_arg): + return (kb_arg or "").strip().lower() == KB_NAME.lower() + + +def _writer(): + author, may_write = _caller() + if not may_write: + raise ToolError("your account may read this KB but not change it") + return author + + +def _can_ask(kb, ctx): + """Whether to ask the user through the client. Elicitation needs the stateless-safe + 2026-07-28 protocol; an older client cannot be asked mid-call by this server and + gets a confirmation code instead.""" + caps = ctx.client_capabilities + return (CONFIRM != "off" and _kb_matches(kb) and bool(caps and caps.elicitation) + and (ctx.protocol_version or "") >= "2026-07-28" and _caller()[1]) + + +def _q_add(title): + return f"Add “{title}” to the '{KB_NAME}' knowledge base" + (f" ({KB_DESC})" if KB_DESC else "") + "?" + + +def _q_withdraw(path): + return f"Withdraw “{path}” from the '{KB_NAME}' inbox? The file is deleted." + + +def _q_retract(path): + return f"Request removal of “{path}” and everything built from it in the '{KB_NAME}' KB?" + + +# Resolvers run before the tool body and receive tool arguments by name. +def _ask_add(kb: str, title: str, ctx: Context): + return Elicit(_q_add(title), Confirm) if _can_ask(kb, ctx) else None + + +def _ask_withdraw(kb: str, path: str, ctx: Context): + return Elicit(_q_withdraw(path), Confirm) if _can_ask(kb, ctx) else None + + +def _ask_retract(kb: str, path: str, ctx: Context): + return Elicit(_q_retract(path), Confirm) if _can_ask(kb, ctx) else None + + +def _code(action, author, payload, ts): + msg = json.dumps([action, KB_NAME, author.email, payload, ts], sort_keys=True, ensure_ascii=False) + return f"{ts}.{hmac.new(_CONFIRM_KEY, msg.encode(), hashlib.sha256).hexdigest()[:24]}" + + +def _gate(action, kb_arg, author, payload, answer, confirmation, question): + """None when the write may go ahead; otherwise a confirmation_required result. + Raises when the target KB is wrong or the user said no.""" + if not _kb_matches(kb_arg): + about = f" ({KB_DESC})" if KB_DESC else "" + raise ToolError(f"This connector is the '{KB_NAME}' KB{about}, not '{kb_arg}'. Nothing was written. " + f"If '{kb_arg}' is another KB, use its own connector. If the user meant this KB, " + f"confirm that with them and call again with kb='{KB_NAME}'.") + if CONFIRM == "off": + return None + if isinstance(answer, AcceptedElicitation) and answer.data is not None: + if answer.data.confirm: + return None + raise ToolError("The user did not confirm. Nothing was written.") + if answer is not None and not isinstance(answer, AcceptedElicitation): + raise ToolError("The user declined. Nothing was written.") + # No elicitation: a signed code binds this exact action, KB, caller and payload. + if confirmation: + ts, _, _ = confirmation.partition(".") + if ts.isdigit() and 0 <= time.time() - int(ts) <= CONFIRM_TTL and \ + hmac.compare_digest(confirmation, _code(action, author, payload, int(ts))): + return None + raise ToolError("That confirmation code is invalid or expired, or the arguments changed since it was " + "issued. Nothing was written. Call again without it for a new one.") + return { + "status": "confirmation_required", + "nothing_written": True, + "kb": KB_NAME, + "kb_description": KB_DESC, + "question_for_user": question, + "confirmation": _code(action, author, payload, int(time.time())), + "expires_in_seconds": CONFIRM_TTL, + "next_step": "Ask the user the question above, in this conversation. Only if they answer yes, call this " + "tool again with exactly the same arguments plus this confirmation code. If they say no " + "or name another KB, do not call it again here.", + } + + +@mcp.tool(annotations=READ, description=_d("""Your own submissions to this KB, made through MCP: pending ones still + in raw/inbox/, and ingested ones in raw/archive/ with the wiki pages and graph + edges built from them, and whether a retraction is already requested. Use it to + find a submission that went to the wrong KB.""")) +def list_my_submissions() -> list[dict]: + author, _ = _caller() + if author is None: + raise ToolError("no authenticated identity on this request") + return _run(kb_store.submissions, author) + + +if WRITE == "inbox": + WRITE_TOOLS.update({"add_to_inbox", "withdraw_submission", "request_retraction"}) + + @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False, + idempotent_hint=False, open_world_hint=False), + description=_d(f"""Submit new knowledge to the '{KB_NAME}' KB's inbox (raw/inbox/) for the next + ingest. `kb` must be '{KB_NAME}': pass it only when the user means this KB, and + ask them first if the material could belong to another connected KB. The user + confirms the target before anything is written; if the result is + confirmation_required, follow its next_step. It does not edit the wiki: tell + the user it was queued. `content` is Markdown with the facts themselves - who, + what, when, decisions, numbers - not a summary of the chat. `source` says where + it came from (meeting, URL, document, person).""")) + def add_to_inbox( + kb: str, title: str, content: str, source: str | None = None, confirmation: str | None = None, + answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_add)] = None, + ) -> dict: + author = _writer() + payload = {"title": title, "content": hashlib.sha256((content or "").encode()).hexdigest(), "source": source} + gate = _gate("add", kb, author, payload, answer, confirmation, _q_add(title)) + return gate or _run(kb_store.add_to_inbox, title, content, author, source=source) + + @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=True, + idempotent_hint=True, open_world_hint=False), + description=_d(f"""Withdraw (delete) one of your own submissions that is still pending in + raw/inbox/ of the '{KB_NAME}' KB - e.g. one sent to the wrong KB. Only the person + who submitted an item can withdraw it; `path` comes from list_my_submissions. Once ingested, a submission is in raw/archive/ and + this refuses: use request_retraction. Confirmed by the user like any write.""")) + def withdraw_submission( + kb: str, path: str, confirmation: str | None = None, + answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_withdraw)] = None, + ) -> dict: + author = _writer() + gate = _gate("withdraw", kb, author, {"path": path}, answer, confirmation, _q_withdraw(path)) + return gate or _run(kb_store.withdraw, path, author) + + @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False, + idempotent_hint=True, open_world_hint=False), + description=_d(f"""Ask for an ingested source in raw/archive/ of the '{KB_NAME}' KB to be + removed together with everything built from it (wiki pages, claims, graph + edges). This files a request in raw/retractions/; the KB's maintainers carry it + out with the ckb-retract workflow, so tell the user it is requested, not done. + `reason` says why, e.g. "sent to the wrong KB; belongs in project-beta". + Only the person who submitted the source can ask; `path` comes from + list_my_submissions. Confirmed by the user like any write.""")) + def request_retraction( + kb: str, path: str, reason: str, confirmation: str | None = None, + answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_retract)] = None, + ) -> dict: + author = _writer() + gate = _gate("retract", kb, author, {"path": path, "reason": reason}, answer, confirmation, _q_retract(path)) + return gate or _run(kb_store.request_retraction, path, author, reason) + + +@mcp.resource("ckb://rules", name="kb-rules", mime_type="text/markdown", + description="The KB's full operating rules (AGENTS.md): layout, page schema, cascade, links.") +def rules() -> str: + return kb_store.rules() + + +@mcp.prompt(description="Answer a question from the knowledge base, with citations.") +def answer_from_kb(question: str) -> str: + return (f"Answer from the Cascade Knowledge Base: {question}\n\n" + "Use search_kb, then read_page the candidates you rely on (and the sources " + "they cite when a fact matters). Cite page paths. Say what is stale, " + "unreviewed (raw/inbox/) or missing rather than filling gaps.") + + +@mcp.custom_route("/health", methods=["GET"]) +async def health(request): + from starlette.responses import JSONResponse + return JSONResponse({"status": "ok", "kb": KB_NAME, "auth": AUTH, "write": WRITE, "git": kb_store.git_mode}) + + +def http_app(): + from mcp.server.transport_security import TransportSecuritySettings + + hosts = [h for h in ENV.get("CKB_MCP_ALLOWED_HOSTS", "").replace(",", " ").split() if h] + security = TransportSecuritySettings(enable_dns_rebinding_protection=bool(hosts), allowed_hosts=hosts) + # Stateless + JSON responses: every request stands alone, which survives + # restarts, reverse proxies and several replicas without session affinity. + app = mcp.streamable_http_app(streamable_http_path=MCP_PATH, stateless_http=True, + json_response=True, transport_security=security) + if AUTH == "token": + app = auth.TokenAuthMiddleware(app, auth.load_tokens(ENV), mcp_path=MCP_PATH) + return app + + +def _redact(value, secrets_): + if isinstance(value, str): + for s in secrets_: + value = value.replace(s, "***") + return value + + +def main(): + if TRANSPORT == "stdio": + if AUTH != "none": + raise SystemExit("stdio has no transport to authenticate; use CKB_MCP_AUTH=none") + mcp.run("stdio") + return + import logging + import uvicorn + + if AUTH == "token": + # The secret-path form puts the token in the request line; keep it out of the access log. + secrets_ = [t["token"] for t in auth.load_tokens(ENV)] + + class Redact(logging.Filter): + def filter(self, record): + if isinstance(record.args, tuple): + record.args = tuple(_redact(a, secrets_) for a in record.args) + return True + + logging.getLogger("uvicorn.access").addFilter(Redact()) + print(f"ckb-mcp: serving '{KB_NAME}' from {kb_store.root} on {HOST}:{PORT}{MCP_PATH} (auth={AUTH}, write={WRITE}, git={kb_store.git_mode})", + file=sys.stderr) + uvicorn.run(http_app(), host=HOST, port=PORT, proxy_headers=True, + forwarded_allow_ips=ENV.get("CKB_MCP_TRUSTED_PROXIES", "127.0.0.1"), log_level="info") + + +if __name__ == "__main__": + main() diff --git a/.agents/modules/mcp/server/tokens.example.json b/.agents/modules/mcp/server/tokens.example.json new file mode 100644 index 0000000..43232a6 --- /dev/null +++ b/.agents/modules/mcp/server/tokens.example.json @@ -0,0 +1,5 @@ +[ + {"name": "Michał Kopeć", "email": "michal.kopec@example.com", "token": "replace-with-secrets.token_urlsafe(32)", "write": true}, + {"name": "Colleague", "email": "colleague@example.com", "token": "replace-with-another-long-random-token"}, + {"name": "Reporting agent", "email": "agent@example.com", "token": "replace-with-a-third-long-random-token", "write": false} +] diff --git a/.agents/modules/mcp/skills/ckb-mcp/SKILL.md b/.agents/modules/mcp/skills/ckb-mcp/SKILL.md new file mode 100644 index 0000000..f77766a --- /dev/null +++ b/.agents/modules/mcp/skills/ckb-mcp/SKILL.md @@ -0,0 +1,174 @@ +--- +name: ckb-mcp +description: Run, deploy, configure or connect this KB's MCP server (.agents/modules/mcp/server/), which lets Claude's web and desktop apps, Claude Code, or any MCP client search and read the KB and submit material to raw/inbox/. Use for "run the MCP server", "deploy the KB server", "connect the KB to Claude web", "add the KB as a connector", "switch MCP auth to OAuth", "add an MCP user", "give an agent read-only access", "rotate the MCP token", "serve several KBs", or "why can't Claude see my KB". +--- + +# MCP server skill + +## Purpose + +The server lives in `.agents/modules/mcp/server/` and runs from there. This +skill sets it up and connects clients to it; it never changes what the server +may read or write. That policy is in `kb.py` and +[D-0007](/docs/decisions/0007-mcp-server-module.md): reads from `wiki/`, +`linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` and the caller's +own requests in `raw/retractions/`. Writes are new files in `raw/inbox/`, the +submitter's own withdrawals from it, and retraction requests in +`raw/retractions/`. Nothing remote ever touches `wiki/`. + +What a client gets: `kb_overview`, `search_kb` (the `ckb-retrieve` ranking +script), `read_page`, `list_pages`, `list_my_submissions`, and, unless +`CKB_MCP_WRITE=off`, `add_to_inbox`, `withdraw_submission` and +`request_retraction`. Also the `ckb://rules` resource (`AGENTS.md`) and the +`answer_from_kb` prompt. + +Every setting is an environment variable; `server/env.example` lists them all +with comments. Read it rather than restating it to the user from memory. + +The user-facing version of these steps is `docs/MCP.md` (Polish: +`docs/MCP.pl.md`). Point the user there, in their language, instead of +restating it at length. + +## Pick the shape first + +Ask only what you can't infer: + +| Client | Transport | Where it runs | +|---|---|---| +| Claude Code or Claude Desktop on this machine | stdio | locally, against this checkout | +| Claude web (claude.ai), mobile, or a team | HTTP | a host with public HTTPS | + +Claude's web app reaches **remote** servers only: Anthropic's cloud calls the +URL, so `localhost` or a VPN-only address will not work for it. + +## Local (stdio) + +Needs Python 3.10+ and `pip install -r .agents/modules/mcp/server/requirements.txt` +(a venv is fine). With `CKB_MCP_GIT=off`, the default, inbox writes are plain +files in this working copy, and `ckb-sync-changes` commits them as usual. + +```bash +claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \ + "$PWD/.agents/modules/mcp/server/server.py" +``` + +Claude Desktop: the same command and `env` in `claude_desktop_config.json` +under `mcpServers`. + +Submissions are authored as this checkout's `git config user.name`/`user.email`, +the identity Rule E uses for the session, unless `CKB_MCP_AUTHOR_NAME`/`_EMAIL` override it. + +## Hosted (HTTP) + +1. **A clone for the server.** It needs its own clone with push access, never + someone's working copy: it pulls before reads and pushes inbox commits. + Recommend an SSH deploy key with write access to this repo only, mounted at + `/run/secrets/ckb-deploy-key`. A token embedded in an HTTPS `CKB_REPO_URL` + works, but git keeps it in plaintext in the clone's `.git/config`. Use it + only when SSH is not available. +2. **Config.** Copy `server/env.example` to `.env` beside + `compose.example.yaml`. Set `CKB_REPO_URL`, `CKB_MCP_PUBLIC_URL` and the auth + block. Generate tokens with + ` -c 'import secrets; print(secrets.token_urlsafe(32))'`, run by the + user. Never put a token in the chat, a commit, the wiki or `workload/`. +3. **Run.** `docker compose -f compose.example.yaml up -d --build` from + `server/`, or run `server.py` directly under systemd with the same env. +4. **TLS.** Put a reverse proxy (Caddy, Traefik, nginx) in front: public HTTPS + to `127.0.0.1:8765`. Set `CKB_MCP_TRUSTED_PROXIES` to the proxy's address. + With token mode in the URL path, turn the proxy's access log off for this + host, or have it strip the path. The server redacts tokens from its own log, + but it cannot reach the proxy's log. +5. **Check.** `curl https:///health` should return `{"status":"ok",...}` + with the expected auth mode. A POST to `/mcp` without credentials should + return 401. + +## Connecting clients + +- **Claude web/desktop, token mode:** Settings → Connectors → Add custom + connector, URL `https:////mcp`. The URL is the secret, so treat + it like a password. +- **Claude web/desktop, OAuth mode:** URL `https:///mcp`. Claude finds the + authorization server through `/.well-known/oauth-protected-resource/mcp`. If + the IdP has no dynamic client registration, create a client there and enter + its ID and secret under the connector's Advanced settings. The redirect URI to + allow is the one Anthropic's current connector docs give for custom + connectors. Check those docs instead of guessing. +- **Claude Code, remote:** + `claude mcp add --transport http ckb https:///mcp --header "Authorization: Bearer "`. + +Team and Enterprise plans may need an owner to add custom connectors. When the +connector cannot be added, say so; don't troubleshoot the server. + +## Switching auth + +`CKB_MCP_AUTH` is the only switch. Restart after changing it. + +- **none:** allowed only on loopback, or with `CKB_MCP_ALLOW_UNAUTHENTICATED=1` + behind a VPN. Never for a public host. +- **token:** one person: `CKB_MCP_TOKEN` (read-write) plus + `CKB_MCP_AUTHOR_NAME`/`_EMAIL`, which become the git author of submissions + (default: the clone's git identity, usually empty in a container). + `CKB_MCP_READ_TOKEN` adds a read-only secret beside it, or replaces it for a + read-only server. Several people or agents: a `CKB_MCP_TOKENS_FILE` (shape in + `tokens.example.json`). An entry is read-only unless it says `"write": true`. + Adding, rotating or demoting someone means editing that file and restarting. + A rotated token's old URL stops working. +- **oauth:** needs an IdP that issues access tokens with this server as + audience: Authentik, Keycloak, Zitadel, Auth0 and Entra ID all can. Set + `CKB_MCP_OAUTH_ISSUER` (exact `iss`), `CKB_MCP_OAUTH_JWKS_URL` (or + introspection for opaque tokens) and `CKB_MCP_PUBLIC_URL`. Restrict with + `CKB_MCP_OAUTH_ALLOWED` / `CKB_MCP_OAUTH_WRITERS`, given as emails or + `@domain`. Leave neither empty when the IdP admits outside accounts (a + social login, say). Each user's `email`/`name` claims become the git author + of their submissions. `CKB_MCP_OAUTH_WRITE_SCOPE` (e.g. `kb:write`) also + makes writing depend on a scope in the token. That is the way to give a + machine client, which has no email, read-only or read-write access. + +**Read-only callers** in any mode see no write tools: `add_to_inbox` is +missing from their tool list, and a direct call is refused. `CKB_MCP_WRITE=off` +makes the whole server read-only. + +## Several knowledge bases + +Run **one server per KB**. Each has its own clone, env file, auth and URL, and +in Claude each becomes its own connector. `compose.example.yaml` shows two +side by side. Prefer a subdomain per KB (`kb-alpha.example.com`). A shared +host with path prefixes also works: `CKB_MCP_PATH=/alpha/mcp`, and the proxy +must route both `/alpha/` and `/.well-known/oauth-protected-resource/alpha/` to +that instance. + +**Keep `CKB_MCP_CONFIRM=auto` whenever a client holds more than one KB +connector.** Every write must name its KB and be confirmed by the user, either +through elicitation or the two-step code (the module README explains both). +Also advise setting the write tools (`add_to_inbox`, `withdraw_submission`, +`request_retraction`) to ask before use in each connector's settings. That +gate cannot be skipped by the model. `off` is for a KB that never shares a +client with another, or for an automated agent's token. Several replicas of +one KB need a shared `CKB_MCP_CONFIRM_SECRET`. + +Only the person who added a document can withdraw it or request its retraction. +Another user, or a maintainer acting through the server, is refused. A +maintainer retracts someone else's source only in a local session, through +`ckb-retract`'s typed override. If something +lands in the wrong KB, its submitter runs `list_my_submissions` there. A pending +item: `withdraw_submission`. An ingested one: `request_retraction`, then +`ckb-retract` in that KB's checkout. Say plainly that git history still holds +it. + +Give every instance a distinct `CKB_MCP_NAME`, and a `CKB_MCP_DESCRIPTION` +saying what the KB covers. The name prefixes every tool description, and the +description goes into the server's instructions. That is how a client holding +several KB connectors knows which one to ask. By default the name is the +origin repo's name, which is fine when the repos are named well. + +With OAuth, one IdP serves them all. Each instance is its own resource +(audience = its public URL), so each needs that audience allowed at the IdP, +or a shared `CKB_MCP_OAUTH_AUDIENCE`. Allow and writer lists are per instance, +so who may read or write is set per project. + +## Reporting + +Say what was configured: mode, URL shape (never the token itself), write mode, +git mode. Record what was set up in `workload/` per Rule D, again without +secrets. If choosing hosted access over local was a real decision for this KB, +offer `ckb-decide`. diff --git a/.agents/modules/software/README.md b/.agents/modules/software/README.md index ff0109c..3d53016 100644 --- a/.agents/modules/software/README.md +++ b/.agents/modules/software/README.md @@ -1,14 +1,16 @@ # `software` module +*Read this in: **English** | [Polski](README.pl.md)* + Opt-in. Install with "install the software module"; remove with "uninstall the -software module". Nothing in here is active until installed — the skills below -live in this folder, not in `.agents/skills/`, precisely so their descriptions +software module". Nothing in here is active until installed. The skills below +live in this folder, not in `.agents/skills/`, so their descriptions stay out of context for knowledge bases that don't document software. ## What it assumes You are building software, and this KB holds the knowledge *about* it. The code -itself lives in `src//` as plain clones — **gitignored**, each with its own +itself lives in `src//` as plain clones: **gitignored**, each with its own remote and its own history. One KB can hold several. The code is not part of the KB's history and may be absent entirely from a fresh @@ -21,30 +23,30 @@ path, owner. **That page is the durable artifact; the clone is a convenience.** | Skill | Does | |---|---| | `ckb-code-map` | Reads a `src/` clone and writes it into `wiki/entities/` as a repository page plus component pages, stamped with the commit it was generated from so staleness is detectable. | -| `ckb-spec` | Owns KB-root specs, delegates per-repo specs to OpenSpec, and bridges both into `wiki/` — archived changes become decision records, current specs become `type: spec` pages. | +| `ckb-spec` | Owns KB-root specs, delegates per-repo specs to OpenSpec, and bridges both into `wiki/`: archived changes become decision records, current specs become `type: spec` pages. | Plus: `src/` and `openspec/` scaffold, a routing block in `AGENTS.md`, `.gitignore` rules for `src/*`, and the `repository`/`component`/`spec` types. -Graph verbs these skills write, from the base vocabulary in -`wiki/graph/index.md`: `ckb-code-map` — `part_of`, `depends_on`, `owns`; -`ckb-spec` — `implements`. No new verbs are introduced. +These skills write graph verbs from the base vocabulary in +`wiki/graph/index.md`: `ckb-code-map` writes `part_of`, `depends_on` and `owns`; +`ckb-spec` writes `implements`. The module adds no new verbs. ## Two spec levels Specs live at **both** levels, and the split is the point: -- **`openspec/` at the KB root** — what and why, across repos. Cross-cutting +- **`openspec/` at the KB root**: what and why, across repos. Cross-cutting contracts that no single repo owns. Served by `ckb-spec` directly, because a root `openspec/` is not a normal OpenSpec install: there is no code beneath it. -- **`src//openspec/`** — how this repo implements it. OpenSpec's native +- **`src//openspec/`**: how this repo implements it. OpenSpec's native case: travels with the code, rides along in the repo's own PRs. Served by OpenSpec's own instructions; `ckb-spec` defers to them and says so plainly when the CLI isn't installed rather than improvising a replacement. The levels are linked by `implements:` / `implemented_by:` frontmatter, which -becomes graph edges. This exists so that two spec levels produce a **lint signal** -when they disagree, instead of two silently divergent truths. A KB-root spec with +becomes graph edges. That way two spec levels that disagree produce a **lint signal** +instead of two silently divergent truths. A KB-root spec with no implementer, or a repo-level spec whose parent was archived, is a finding. ## What it does not do @@ -64,9 +66,9 @@ install steps, the daily propose → apply → archive loop, and the reason ## Design record -- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md) — why modules are files in the repo. -- [D-0002](../../../docs/decisions/0002-software-module-design.md) — why gitignored clones, both spec levels, hybrid vendoring. +- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): why modules are files in the repo. +- [D-0002](../../../docs/decisions/0002-software-module-design.md): why gitignored clones, both spec levels, hybrid vendoring. --- -*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE).* +*Licensed under the Apache License, Version 2.0 - see [LICENSE](../../../LICENSE).* diff --git a/.agents/modules/software/README.pl.md b/.agents/modules/software/README.pl.md new file mode 100644 index 0000000..d1f47da --- /dev/null +++ b/.agents/modules/software/README.pl.md @@ -0,0 +1,83 @@ +# Moduł `software` + +*Read this in: [English](README.md) | **Polski*** + +Opcjonalny. Instalacja: „install the software module”; usunięcie: „uninstall +the software module”. Dopóki moduł nie jest zainstalowany, nic tutaj nie +działa. Poniższe skille leżą w tym folderze, a nie w `.agents/skills/`, +po to, żeby ich opisy nie zajmowały kontekstu w bazach, które nie +dokumentują oprogramowania. + +## Co zakłada + +Tworzysz oprogramowanie, a ta baza przechowuje wiedzę *o* nim. Sam kod leży w +`src//` jako zwykłe klony: **ignorowane przez git**, każdy z własnym +zdalnym repozytorium i własną historią. Jedna baza może ich mieć kilka. + +Kod nie jest częścią historii bazy i może go w ogóle nie być w świeżym klonie. +To celowe i dlatego moduł zapisuje dla każdego repozytorium stronę encji +`type: repository`: adres zdalnego repozytorium, domyślna gałąź, język, +polecenie budowania, ścieżka, właściciel. **Trwałym zapisem jest ta strona; +klon to tylko wygoda.** + +## Co dodaje + +| Skill | Co robi | +|---|---| +| `ckb-code-map` | Czyta klon `src/` i zapisuje go w `wiki/entities/` jako stronę repozytorium oraz strony komponentów, oznaczone commitem, z którego powstały, żeby dało się wykryć ich nieaktualność. | +| `ckb-spec` | Zarządza specyfikacjami na poziomie bazy, specyfikacje poszczególnych repozytoriów zostawia OpenSpec i łączy oba poziomy z `wiki/`: zarchiwizowane zmiany stają się rekordami decyzji, bieżące specyfikacje stronami `type: spec`. | + +Do tego: szkielet `src/` i `openspec/`, blok routingu w `AGENTS.md`, reguły +`.gitignore` dla `src/*` oraz typy `repository`/`component`/`spec`. + +Te skille zapisują czasowniki grafu z bazowego słownika w +`wiki/graph/index.md`: `ckb-code-map` zapisuje `part_of`, `depends_on` i `owns`, +a `ckb-spec` — `implements`. Moduł nie wprowadza nowych czasowników. + +## Dwa poziomy specyfikacji + +Specyfikacje istnieją na **obu** poziomach i właśnie o ten podział chodzi: + +- **`openspec/` w katalogu głównym bazy**: co i dlaczego, ponad + repozytoriami. Kontrakty przekrojowe, których nie posiada żadne pojedyncze + repozytorium. Obsługuje je bezpośrednio `ckb-spec`, bo `openspec/` w + katalogu głównym nie jest zwykłą instalacją OpenSpec: nie ma pod nim kodu. +- **`src//openspec/`**: jak to repozytorium to realizuje. Naturalny + przypadek OpenSpec: podróżuje razem z kodem i trafia do PR-ów samego + repozytorium. Obsługują go instrukcje samego OpenSpec; `ckb-spec` się im + podporządkowuje i mówi wprost, gdy CLI nie jest zainstalowane, zamiast + improwizować zastępstwo. + +Poziomy łączą pola frontmatter `implements:` / `implemented_by:`, które stają +się krawędziami grafu. Dzięki temu dwa poziomy specyfikacji, które się rozjadą, +dają **sygnał w lincie** zamiast dwóch po cichu rozbieżnych prawd. Specyfikacja na poziomie bazy bez implementacji albo specyfikacja +repozytorium, której rodzic został zarchiwizowany, to znalezisko. + +## Czego nie robi + +- **`src/` nie jest warstwą kaskady.** To materiał dowodowy, jak + `raw/archive/`. `ckb-retrieve` może otworzyć kod i zacytować go, żeby + zweryfikować twierdzenie; nigdy nie odpowiada nim na pytanie „czym jest + encja X”, a `ckb-ingest` nie traktuje kodu jako materiału do skrzynki. Bez + tej reguły każdy ingest zamieniałby twój kod w strony wiki. +- **Nie commituje ani nie wypycha repozytoriów z `src/`.** To osobne + repozytoria z osobnymi zdalnymi. `ckb-sync-changes` nigdy nie wykonuje + `git add` w `src/`. + +## Konfiguracja OpenSpec + +Zobacz [docs/OPENSPEC.pl.md](../../../docs/OPENSPEC.pl.md) +([English](../../../docs/OPENSPEC.md)): instalacja, codzienna pętla +propose → apply → archive i powód, dla którego `openspec init` nigdy nie może +być uruchomione w katalogu głównym bazy. + +## Zapis decyzji projektowych + +- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md): dlaczego moduły są plikami w repozytorium. +- [D-0002](../../../docs/decisions/0002-software-module-design.md): dlaczego ignorowane klony, oba poziomy specyfikacji i hybrydowe vendorowanie. + +Rekordy decyzji są po angielsku. + +--- + +*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../../../LICENSE).* diff --git a/.agents/skills/ckb-add-conversation/SKILL.md b/.agents/skills/ckb-add-conversation/SKILL.md index c2d9426..e719e3b 100644 --- a/.agents/skills/ckb-add-conversation/SKILL.md +++ b/.agents/skills/ckb-add-conversation/SKILL.md @@ -7,27 +7,11 @@ description: Save the current Claude Code conversation (or an earlier session of ## Purpose -Keep a verbatim copy of a conversation inside the KB, on the user's request -only. Two jobs: - -1. **Save** — copy the session's transcript file into - `raw/saved-conversations//` and render it as Markdown. -2. **Recall** — when the user asks whether something was discussed or what - instruction they gave earlier, search the saved conversations and answer - from them, quoting the exact exchange. - -What this skill is **not**: - -- Not retrieval. `raw/saved-conversations/` is outside the cascade. - `ckb-retrieve` never reads it, lint never fingerprints it, and nothing in - it counts as a source for a wiki page until it has been ingested. -- Not ingest. A saved conversation becomes wiki knowledge only when the user - copies its `.md` into `raw/inbox/` and says "Ingest" — the copy is theirs - to make, so the choice of what enters the wiki stays explicit. -- Not automatic by default. The agent asks at session end (Rule E) and - saves only on a clear yes. Never save because a session "seems - important". The one exception is the `autosave` switch below, which the - user turns on deliberately. +Verbatim copies live in `raw/saved-conversations/`, outside the cascade: +`ckb-retrieve` never reads them, lint never fingerprints them, and nothing in +them reaches `wiki/` until the user copies the `.md` into `raw/inbox/` and +says "Ingest". Never save because a session "seems important"; the only +automatic path is the `autosave` switch below. ## Where transcripts come from @@ -204,7 +188,8 @@ touch one that is not valid JSON. **Never change machine configuration silently.** Two moments call for the check, and both end in a question, not an action: -1. *Session start* (Rule E) — when `autosave: true`, run `--check`. On exit 1 +1. *Session start* (Rule E, via `session_start.py`) — when `autosave: true`, + `--check` runs. On exit 1 tell the user in one line what is out of line and ask whether to install (or remove) the hook on this machine. Apply only on a yes. If they decline, do not ask again this session; autosave then relies on the diff --git a/.agents/skills/ckb-decide/SKILL.md b/.agents/skills/ckb-decide/SKILL.md index aa9aaf4..b381f43 100644 --- a/.agents/skills/ckb-decide/SKILL.md +++ b/.agents/skills/ckb-decide/SKILL.md @@ -7,18 +7,11 @@ description: Record a numbered, append-only decision record in wiki/decisions/, ## Purpose -A decision records what was chosen at a point in time, by whom, and why. Unlike an -entity page it is never rewritten to reflect a later change of mind — a new decision -supersedes the old one and both stay on the record. - -This skill owns both **recording** (turning "we decided X" into a numbered, linked, -logged record under `wiki/decisions/`, supersession wired in both directions) and -**looking up** (answering questions about decisions already recorded, scoped to -`wiki/decisions/` rather than the whole wiki). - -Writes only inside `wiki/`: `wiki/decisions/`, its `index.md` and `log.md`, -`wiki/graph/edges.json`, and a pointer line in `wiki/log.md`. Never edits an existing -decision's substance — see Rule: decisions are append-only, below. +A decision is never rewritten to reflect a later change of mind: a new one +supersedes it and both stay on the record. Recording wires supersession in +both directions; look-up is scoped to `wiki/decisions/`, not the whole wiki. +Writes only `wiki/decisions/`, its `index.md` and `log.md`, +`wiki/graph/edges.json`, and a pointer line in `wiki/log.md`. ## The decision record format diff --git a/.agents/skills/ckb-document/SKILL.md b/.agents/skills/ckb-document/SKILL.md new file mode 100644 index 0000000..2673052 --- /dev/null +++ b/.agents/skills/ckb-document/SKILL.md @@ -0,0 +1,155 @@ +--- +name: ckb-document +description: Prepare a new document from a document template in templates/ - read the template, treat each section's comment as an instruction (ask the user, pull from a named wiki page or file, keep to a length), fill the placeholders and write the result to outputs/documents/. Also lists the templates available and writes a new template on request. Use for "prepare a new document using template X", "new document from template X", "create a status report from the template", "what templates do I have", "list templates", or "make a template for X". Not for the tooling layer: "upgrade the template" is ckb-upgrade. +--- + +# Document skill + +## Purpose + +The template is the brief, the wiki is the evidence, the user fills what +neither covers. Templates are the user's files: read them, write a new one +only on request, never rewrite an existing one. Nothing here touches +`wiki/`, so Rule B does not apply; Rule D does. + +## Template format + +```markdown +--- +type: template +tldr: One line saying what kind of document this produces. +output: outputs/documents/{{date}}-handover-{{slug}}.md # optional +--- + +# Handover: {{subject}} + + + +## Current state + + + +*Prepared from the knowledge base on {{date}}.* +``` + +How to read it: + +| Element | Meaning | +|---|---| +| `` | An instruction for this section. Follow it, then drop it. It may say to ask the user, name a source (a wiki page, a `raw/` file, a `linked/` or `libs/` page, a URL), set a length or tone, or say when to drop the section. | +| Any other text | Boilerplate. Copy it verbatim: headings, closing lines, signatures. | +| `{{date}}`, `{{author}}`, `{{slug}}` | Filled in without asking: today, the session identity (name, or `Name ` in frontmatter), a short kebab-case slug of the document's subject. | +| Any other `{{name}}` | Asked for once, unless a comment says where it comes from. The same placeholder repeated gets the same value. | +| `output:` | Where the document goes. Default: `outputs/documents/{{date}}-