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

6.6 KiB

mcp module

Read this in: English | Polski

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 (Polski). The ckb-mcp skill walks an agent through the same steps.

Design record

  • D-0001: why modules are files in the repo.
  • D-0007: 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.