Fixes F17-F19 from the 2.0.0 script review: - lint check 15 scans hidden folders, key files, dotfiles and extensionless text; finds unquoted secret-looking assignments; reports files over 50 MB instead of skipping them silently - mcp: search filtered by the read policy, query after `--`, case/trailing-dot-insensitive .local.yaml refusal, verified OAuth email only, DNS-rebinding protection on by default, single-use codes - capture: link-local/metadata always refused, private networks need --allow-private (also on redirects), total download limit, charset fallback and <meta charset>, <form> kept, svg title ignored, safe collision-free binary names with dedup Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
177 lines
9.3 KiB
Markdown
177 lines
9.3 KiB
Markdown
---
|
|
name: ckb-mcp
|
|
description: Run, deploy, configure or connect this KB's MCP server (.agents/modules/mcp/server/), which lets Claude's web and desktop apps, Claude Code, or any MCP client search and read the KB and submit material to raw/inbox/. Use for "run the MCP server", "deploy the KB server", "connect the KB to Claude web", "add the KB as a connector", "switch MCP auth to OAuth", "add an MCP user", "give an agent read-only access", "rotate the MCP token", "serve several KBs", or "why can't Claude see my KB".
|
|
---
|
|
|
|
# MCP server skill
|
|
|
|
## Purpose
|
|
|
|
The server lives in `.agents/modules/mcp/server/` and runs from there. This
|
|
skill sets it up and connects clients to it; it never changes what the server
|
|
may read or write. That policy is in `kb.py` and
|
|
[D-0007](/docs/decisions/0007-mcp-server-module.md): reads from `wiki/`,
|
|
`linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` and the caller's
|
|
own requests in `raw/retractions/`. Writes are new files in `raw/inbox/`, the
|
|
submitter's own withdrawals from it, and retraction requests in
|
|
`raw/retractions/`. Nothing remote ever touches `wiki/`.
|
|
|
|
What a client gets: `kb_overview`, `search_kb` (the `ckb-retrieve` ranking
|
|
script), `read_page`, `list_pages`, `list_my_submissions`, and, unless
|
|
`CKB_MCP_WRITE=off`, `add_to_inbox`, `withdraw_submission` and
|
|
`request_retraction`. Also the `ckb://rules` resource (`AGENTS.md`) and the
|
|
`answer_from_kb` prompt.
|
|
|
|
Every setting is an environment variable; `server/env.example` lists them all
|
|
with comments. Read it rather than restating it to the user from memory.
|
|
|
|
The user-facing version of these steps is `docs/MCP.md` (Polish:
|
|
`docs/MCP.pl.md`). Point the user there, in their language, instead of
|
|
restating it at length.
|
|
|
|
## Pick the shape first
|
|
|
|
Ask only what you can't infer:
|
|
|
|
| Client | Transport | Where it runs |
|
|
|---|---|---|
|
|
| Claude Code or Claude Desktop on this machine | stdio | locally, against this checkout |
|
|
| Claude web (claude.ai), mobile, or a team | HTTP | a host with public HTTPS |
|
|
|
|
Claude's web app reaches **remote** servers only: Anthropic's cloud calls the
|
|
URL, so `localhost` or a VPN-only address will not work for it.
|
|
|
|
## Local (stdio)
|
|
|
|
Needs Python 3.10+ and `pip install -r .agents/modules/mcp/server/requirements.txt`
|
|
(a venv is fine). With `CKB_MCP_GIT=off`, the default, inbox writes are plain
|
|
files in this working copy, and `ckb-sync-changes` commits them as usual.
|
|
|
|
```bash
|
|
claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \
|
|
<python> "$PWD/.agents/modules/mcp/server/server.py"
|
|
```
|
|
|
|
Claude Desktop: the same command and `env` in `claude_desktop_config.json`
|
|
under `mcpServers`.
|
|
|
|
Submissions are authored as this checkout's `git config user.name`/`user.email`,
|
|
the identity Rule E uses for the session, unless `CKB_MCP_AUTHOR_NAME`/`_EMAIL` override it.
|
|
|
|
## Hosted (HTTP)
|
|
|
|
1. **A clone for the server.** It needs its own clone with push access, never
|
|
someone's working copy: it pulls before reads and pushes inbox commits.
|
|
Recommend an SSH deploy key with write access to this repo only, mounted at
|
|
`/run/secrets/ckb-deploy-key`. A token embedded in an HTTPS `CKB_REPO_URL`
|
|
works, but git keeps it in plaintext in the clone's `.git/config`. Use it
|
|
only when SSH is not available.
|
|
2. **Config.** Copy `server/env.example` to `.env` beside
|
|
`compose.example.yaml`. Set `CKB_REPO_URL`, `CKB_MCP_PUBLIC_URL` and the auth
|
|
block. Generate tokens with
|
|
`<python> -c 'import secrets; print(secrets.token_urlsafe(32))'`, run by the
|
|
user. Never put a token in the chat, a commit, the wiki or `workload/`.
|
|
3. **Run.** `docker compose -f compose.example.yaml up -d --build` from
|
|
`server/`, or run `server.py` directly under systemd with the same env.
|
|
4. **TLS.** Put a reverse proxy (Caddy, Traefik, nginx) in front: public HTTPS
|
|
to `127.0.0.1:8765`. Set `CKB_MCP_TRUSTED_PROXIES` to the proxy's address.
|
|
With token mode in the URL path, turn the proxy's access log off for this
|
|
host, or have it strip the path. The server redacts tokens from its own log,
|
|
but it cannot reach the proxy's log.
|
|
5. **Check.** `curl https://<host>/health` should return `{"status":"ok",...}`
|
|
with the expected auth mode. A POST to `/mcp` without credentials should
|
|
return 401.
|
|
|
|
## Connecting clients
|
|
|
|
- **Claude web/desktop, token mode:** Settings → Connectors → Add custom
|
|
connector, URL `https://<host>/<token>/mcp`. The URL is the secret, so treat
|
|
it like a password.
|
|
- **Claude web/desktop, OAuth mode:** URL `https://<host>/mcp`. Claude finds the
|
|
authorization server through `/.well-known/oauth-protected-resource/mcp`. If
|
|
the IdP has no dynamic client registration, create a client there and enter
|
|
its ID and secret under the connector's Advanced settings. The redirect URI to
|
|
allow is the one Anthropic's current connector docs give for custom
|
|
connectors. Check those docs instead of guessing.
|
|
- **Claude Code, remote:**
|
|
`claude mcp add --transport http ckb https://<host>/mcp --header "Authorization: Bearer <token>"`.
|
|
|
|
Team and Enterprise plans may need an owner to add custom connectors. When the
|
|
connector cannot be added, say so; don't troubleshoot the server.
|
|
|
|
## Switching auth
|
|
|
|
`CKB_MCP_AUTH` is the only switch. Restart after changing it.
|
|
|
|
- **none:** allowed only on loopback, or with `CKB_MCP_ALLOW_UNAUTHENTICATED=1`
|
|
behind a VPN. Never for a public host.
|
|
- **token:** one person: `CKB_MCP_TOKEN` (read-write) plus
|
|
`CKB_MCP_AUTHOR_NAME`/`_EMAIL`, which become the git author of submissions
|
|
(default: the clone's git identity, usually empty in a container).
|
|
`CKB_MCP_READ_TOKEN` adds a read-only secret beside it, or replaces it for a
|
|
read-only server. Several people or agents: a `CKB_MCP_TOKENS_FILE` (shape in
|
|
`tokens.example.json`). An entry is read-only unless it says `"write": true`.
|
|
Adding, rotating or demoting someone means editing that file and restarting.
|
|
A rotated token's old URL stops working.
|
|
- **oauth:** needs an IdP that issues access tokens with this server as
|
|
audience: Authentik, Keycloak, Zitadel, Auth0 and Entra ID all can. Set
|
|
`CKB_MCP_OAUTH_ISSUER` (exact `iss`), `CKB_MCP_OAUTH_JWKS_URL` (or
|
|
introspection for opaque tokens) and `CKB_MCP_PUBLIC_URL`. Restrict with
|
|
`CKB_MCP_OAUTH_ALLOWED` / `CKB_MCP_OAUTH_WRITERS`, given as emails or
|
|
`@domain`. Leave neither empty when the IdP admits outside accounts (a
|
|
social login, say). An `email` claim counts only with `email_verified:
|
|
true`; for an IdP that never sends that claim (Entra ID access tokens),
|
|
set `CKB_MCP_OAUTH_TRUST_EMAIL=1`, else such users match only by subject.
|
|
Each user's `email`/`name` claims become the git author of their
|
|
submissions. `CKB_MCP_OAUTH_WRITE_SCOPE` (e.g. `kb:write`) also
|
|
makes writing depend on a scope in the token. That is the way to give a
|
|
machine client, which has no email, read-only or read-write access.
|
|
|
|
**Read-only callers** in any mode see no write tools: `add_to_inbox` is
|
|
missing from their tool list, and a direct call is refused. `CKB_MCP_WRITE=off`
|
|
makes the whole server read-only.
|
|
|
|
## Several knowledge bases
|
|
|
|
Run **one server per KB**. Each has its own clone, env file, auth and URL, and
|
|
in Claude each becomes its own connector. `compose.example.yaml` shows two
|
|
side by side. Prefer a subdomain per KB (`kb-alpha.example.com`). A shared
|
|
host with path prefixes also works: `CKB_MCP_PATH=/alpha/mcp`, and the proxy
|
|
must route both `/alpha/` and `/.well-known/oauth-protected-resource/alpha/` to
|
|
that instance.
|
|
|
|
**Keep `CKB_MCP_CONFIRM=auto` whenever a client holds more than one KB
|
|
connector.** Every write must name its KB and be confirmed by the user, either
|
|
through elicitation or the two-step code (the module README explains both).
|
|
Also advise setting the write tools (`add_to_inbox`, `withdraw_submission`,
|
|
`request_retraction`) to ask before use in each connector's settings. That
|
|
gate cannot be skipped by the model. `off` is for a KB that never shares a
|
|
client with another, or for an automated agent's token. Several replicas of
|
|
one KB need a shared `CKB_MCP_CONFIRM_SECRET`.
|
|
|
|
Only the person who added a document can withdraw it or request its retraction.
|
|
Another user, or a maintainer acting through the server, is refused. A
|
|
maintainer retracts someone else's source only in a local session, through
|
|
`ckb-retract`'s typed override. If something
|
|
lands in the wrong KB, its submitter runs `list_my_submissions` there. A pending
|
|
item: `withdraw_submission`. An ingested one: `request_retraction`, then
|
|
`ckb-retract` in that KB's checkout. Say plainly that git history still holds
|
|
it.
|
|
|
|
Give every instance a distinct `CKB_MCP_NAME`, and a `CKB_MCP_DESCRIPTION`
|
|
saying what the KB covers. The name prefixes every tool description, and the
|
|
description goes into the server's instructions. That is how a client holding
|
|
several KB connectors knows which one to ask. By default the name is the
|
|
origin repo's name, which is fine when the repos are named well.
|
|
|
|
With OAuth, one IdP serves them all. Each instance is its own resource
|
|
(audience = its public URL), so each needs that audience allowed at the IdP,
|
|
or a shared `CKB_MCP_OAUTH_AUDIENCE`. Allow and writer lists are per instance,
|
|
so who may read or write is set per project.
|
|
|
|
## Reporting
|
|
|
|
Say what was configured: mode, URL shape (never the token itself), write mode,
|
|
git mode. Record what was set up in `workload/` per Rule D, again without
|
|
secrets. If choosing hosted access over local was a real decision for this KB,
|
|
offer `ckb-decide`.
|