121 lines
6.6 KiB
Markdown
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).*
|