ckb/.agents/modules/mcp/skills/ckb-mcp/SKILL.md
Michał Kopeć 84018323a2 Template 2.0.4: secret scan coverage, mcp and capture hardening
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>
2026-11-11 15:46:38 +01:00

9.3 KiB

name description
ckb-mcp 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: 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.

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.