# `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//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).*