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 inraw/inbox/, andckb-ingestturns 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.yamland 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:
- 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. - 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_requiredwith 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. - Mistakes can be undone.
withdraw_submissiondeletes a pending item;request_retractionqueues an ingested one forckb-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.