ckb/docs/decisions/0007-mcp-server-module.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

170 lines
9.5 KiB
Markdown

---
type: decision
tldr: The opt-in `mcp` module serves the KB over MCP; remote clients read the cascade and write only to raw/inbox/ (add, withdraw own) and raw/retractions/ (request removal), never wiki/, auth is one flag (none/token/oauth), and the server runs in place from the module folder against its own clone.
status: accepted
decided_on: 2026-10-29
decided_by: Michał Kopeć
affects: /docs/decisions/0001-opt-in-file-based-kb-modules.md
confidence: 0.8
quality: 0.8
last_updated: 2026-10-29
freshness_window_days: 365
retention: high
---
# D-0007 — The opt-in `mcp` server module
**Status:** Accepted · **Decided:** 2026-10-29 · **Deciders:** Michał Kopeć
## Context
The knowledge in a KB is only reachable where an agent has a checkout and the
skills: Claude Code, in practice. The user wants the same knowledge in tools
that accept MCP connectors, Claude's web UI above all, and wants to add new
information from there, not only read it. Most of the time there is one user,
but a team may follow, so authentication has to start simple and grow without
a redeploy.
Claude's web app connects only to **remote** MCP servers: Anthropic's cloud
calls the URL, so the server needs public HTTPS. The web connector also
cannot send a custom header. Without OAuth, a secret must travel in the URL.
## Decision
**A module, not core.** Serving the KB is useful to some KBs and needs a host
and a Python ≥3.10 runtime, so it ships under `.agents/modules/mcp/` per
[[D-0001]] / [D-0001](/docs/decisions/0001-opt-in-file-based-kb-modules.md).
It installs one skill (`ckb-mcp`) and a routing block. The server runs in place
from `server/`, so a template upgrade replaces it with the rest of the module.
**Reads follow the cascade, through the existing retrieval script.**
`search_kb` runs `ckb-retrieve`'s `retrieve_candidates.py`, so remote and local
answers rank alike. `read_page` serves `wiki/`, `linked/`, `libs/`,
`raw/inbox/`, `raw/archive/` and `outputs/`, and nothing else, except that a
caller may read their own requests in `raw/retractions/`. A request's reason
can reveal why material was confidential, so nobody else sees it. The same
areas apply inside each
`linked/<name>/`. No symlink is followed except `linked/<name>` itself, because
a committed link such as `wiki/x.md -> ../.git/config` would otherwise serve whatever
it points at. `workload/`,
`raw/saved-conversations/`, dotfiles and `*.local.yaml` stay private.
**Remote writes never touch `wiki/`.** The main one is a new file in `raw/inbox/`; the undo paths below add a withdrawal and a retraction request. A submission carries provenance
frontmatter (`submitted_by`, `submitted_at`, `via: mcp`, `source`) and is
committed with the submitter as git author. `ckb-ingest` turns it into wiki
pages, keeping the log, schema, cross-links and review where they already
live.
**Auth is one flag: `CKB_MCP_AUTH=none|token|oauth`.** `token` takes a single
secret or a per-person file with a write bit, and accepts either
`Authorization: Bearer` or a secret path `/<token>/mcp` for Claude web. `oauth`
makes the server an OAuth 2.1 resource server: it advertises an external
authorization server and verifies its JWTs by JWKS, or introspects opaque
tokens, with allow and writer lists. The server never issues tokens itself.
Read-only is available in both modes: a read-only token or a token-file entry
without `write: true`, an OAuth user outside the writer list, or an OAuth token
missing `CKB_MCP_OAUTH_WRITE_SCOPE`. Read-only callers are not shown the write
tools.
**One server per KB, each named.** Several KBs mean several instances, each
with its own clone, auth and URL. Claude holds one connector per KB.
`CKB_MCP_NAME` (default: the origin repo's name) prefixes every tool
description, and `CKB_MCP_DESCRIPTION` goes into the server's instructions,
because the tool names are identical across instances.
**Every write names its KB and is confirmed by the user.** With several KB
connectors in one client, a misrouted write can put one client's material into
another's KB. Each write tool takes a required `kb` argument that must equal the
server's name. With `CKB_MCP_CONFIRM=auto` the user then confirms the write:
through MCP elicitation when the client supports it on the stateless-safe
2026-07-28 protocol, and otherwise by repeating the call with a signed code.
The code is bound to the KB, the caller and the exact arguments, and expires in
15 minutes. The two-step form relies on the model asking the user, so the docs
also advise per-tool approval in the client, the one gate a model cannot skip.
**Undo is part of the write path, and only for the person who added the
document.** `withdraw_submission` deletes the caller's own pending inbox item.
`request_retraction` accepts only the source's `submitted_by`. `ckb-retract`
re-checks this locally, falling back to the git author who added the file. Only
`ckb-retract` in a local session may override the owner, for a maintainer who types an
explicit confirmation and is logged as overriding: the KB exists to share knowledge,
so a source must not be stranded when its submitter leaves or changes email. An ingested source cannot be pulled out remotely,
because its content has spread into pages, claims and edges. Instead
`request_retraction` files a request in `raw/retractions/`, and the core
`ckb-retract` skill unwinds exactly what that source contributed, with the
user approving the plan. Retraction is core, not module: a source filed in the
wrong KB, or later found wrong, needs unwinding however it arrived.
**Git: its own clone, three modes.** `CKB_MCP_GIT=off|commit|sync`. A hosted
server uses `sync`. Before every write it fetches and hard-resets its clone to
the remote branch, applies the change, commits and pushes. A rejected push is
retried once from a fresh reset; a second rejection resets again and reports
that nothing was saved. Reads reset at most once per interval. The clone holds
nothing but writes already pushed, so a reset loses nothing, and the clone can
never diverge. That matters now that a withdrawal deletes a file someone may
have edited upstream. Because sync resets, the server refuses to start on a
checkout with local changes or unpushed commits: it must have its own clone,
never a person's working copy.
**Stateless HTTP with JSON responses.** Every request stands alone, so the
server survives restarts and proxies, and can run as several replicas without
session affinity.
## Rationale
Keeping remote writes out of `wiki/` keeps them small and reviewable. Two submissions never
conflict, a bad one is a file to delete rather than a page to repair, and a
remote model's claims cannot enter the wiki unreviewed. Direct page edits would
mean re-implementing ingest's log, schema and cross-link duties inside the
server, and trusting a model that cannot see the skills to follow them.
Token mode exists because a one-person KB needs no identity provider, and
Claude web needs a header-free form. OAuth is the right shape for a team, but
only as a resource server: issuing tokens means storing credentials and
implementing login, consent and client registration, all of which an existing
IdP already does.
## Consequences
- `ckb-ingest` sees inbox items with `via: mcp` and credits `submitted_by`. The
module's routing block tells it to treat them as unreviewed claims.
- The server's commits arrive through `ckb-sync-changes` like anyone else's.
- In token mode the URL is the secret. The server redacts it from its own
access log. A reverse proxy's log is the operator's to switch off.
- No page schema change; `kb_schema_version` stays `1.5`.
## Alternatives considered
- **A generic git or filesystem MCP server.** Nothing to write, but it ignores
the cascade and lets a client edit `wiki/` with no log, schema or review.
- **Direct page edits, or edits on a branch for review.** A branch keeps review,
but a proposed edit still needs the ingest duties done by the remote model.
Deferred to a possible later `propose_page_edit` tool. The inbox covers
adding knowledge, which was the stated need.
- **Server-side confirmation only by elicitation.** That gate is the strongest,
but writes would fail outright for every client without elicitation on the
current protocol.
- **Remote removal of ingested content.** One call would undo a misfiled
ingest, but it hands wiki surgery (which claims only that source supported)
to a model that cannot see the skills. A request plus `ckb-retract` keeps a
person in the loop.
- **Built-in OAuth authorization server.** Self-contained, but it puts
credential storage, login and client registration in the KB's tooling.
Rejected in favour of verifying an external IdP's tokens.
- **One server process serving several KBs under separate paths.** Fewer
processes, but each KB needs its own OAuth resource metadata at the root
`/.well-known/` path, its own lifespan and its own access lists anyway.
Containers per KB cost little and keep each KB's credentials and failures
apart.
- **Syncing the wiki to Drive or Notion and using their connectors.** No server
to host, but writes come back outside git and search ignores the cascade.
## Sources
Chat conversation, 2026-10-29: options for exposing the KB to MCP clients;
the user chose a hosted, KB-aware server with OAuth as a switchable option and
a likely move from one user to several. Same day: read-only access for some
OAuth users and for agents on tokens, and several KBs connected to one Claude
account. Same day: a misrouted write was judged unsafe with several KBs,
leading to the required `kb` argument, user confirmation, and withdraw and
retraction.