170 lines
9.5 KiB
Markdown
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.
|