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

121 lines
6.6 KiB
Markdown

# `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` | `ABOUT.md` (what the KB is for, as its owner states it), 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/<token>/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 `[<name>]`, 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).*