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>
198 lines
9.9 KiB
Markdown
198 lines
9.9 KiB
Markdown
# Using this knowledge base from Claude and other MCP clients
|
|
|
|
*Read this in: **English** | [Polski](MCP.pl.md)*
|
|
|
|
The optional `mcp` module puts this knowledge base behind an MCP server. You
|
|
can then search it, read it and add to it from Claude's web, desktop and mobile
|
|
apps (as a custom connector), from Claude Code, or from any other agent that
|
|
speaks MCP. You don't need a checkout of the repo on the device you're using.
|
|
|
|
This guide is for the person setting it up and using it. For the design
|
|
reasons behind it, see
|
|
[D-0007](decisions/0007-mcp-server-module.md). For the module's file layout,
|
|
see [its README](../.agents/modules/mcp/README.md).
|
|
|
|
---
|
|
|
|
## What a connected client can do
|
|
|
|
| You say (in Claude) | What happens |
|
|
|---|---|
|
|
| "What do we know about the Atlas retry policy?" | Claude searches the KB, reads the pages it relies on, and answers with page paths cited |
|
|
| "Add this to the KB: ..." | The material goes to `raw/inbox/` as a new file, with your name, the date and the source. It is **not** in the wiki yet: the next "Ingest" in a local session turns it into pages |
|
|
| "What have I sent to this KB?" | Lists your submissions: still pending, or already ingested along with the pages built from them |
|
|
| "Take back what I just sent, it was the wrong KB" | Withdraws a pending submission (the file is deleted) |
|
|
| "Remove what came from that note, it belonged in another KB" | For a submission that was already ingested: files a request in `raw/retractions/`. The next local session carries it out with `ckb-retract` after you approve the plan |
|
|
|
|
A remote client **never edits `wiki/` directly**. Ingest and retraction stay in
|
|
your local sessions, where the log, the page schema and the review steps apply.
|
|
|
|
Only the person who added a document can withdraw it or ask for its removal.
|
|
A maintainer can still retract any source in a local session, with typed
|
|
confirmation, so nothing is stranded when its submitter has left.
|
|
|
|
---
|
|
|
|
## 1. Install the module
|
|
|
|
In a local session, say **"install the mcp module"**. That adds the `ckb-mcp`
|
|
skill and records the module in `ckb.yaml`. The server itself lives in
|
|
`.agents/modules/mcp/server/` and does nothing until someone starts it.
|
|
|
|
From then on, "help me deploy the MCP server" or "connect the KB to Claude
|
|
web" walks you through the rest. The steps below are the same, written out.
|
|
|
|
---
|
|
|
|
## 2. Choose where it runs
|
|
|
|
| You want it in | Run it | Notes |
|
|
|---|---|---|
|
|
| Claude Code or Claude Desktop on this computer | locally, over stdio | Nothing to host. Submissions are plain files in your working copy |
|
|
| Claude on the web or mobile, or for a team | on a server with public HTTPS | Claude's web app calls the URL from Anthropic's cloud, so `localhost` or a VPN-only address won't work |
|
|
|
|
### Locally (stdio)
|
|
|
|
You need Python 3.10 or newer, then:
|
|
|
|
```bash
|
|
pip install -r .agents/modules/mcp/server/requirements.txt
|
|
claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \
|
|
python3 "$PWD/.agents/modules/mcp/server/server.py"
|
|
```
|
|
|
|
Submissions are authored as your `git config user.name`/`user.email`.
|
|
`ckb-sync-changes` commits them like any other change.
|
|
|
|
### Hosted (HTTPS)
|
|
|
|
1. **Give the server its own clone** with push access. Never point it at
|
|
someone's working copy: before every write it resets its clone to the
|
|
remote, and it refuses to start on a clone with local changes. Use an SSH
|
|
**deploy key** with write access to this one repo.
|
|
2. **Configure it.** Copy `server/env.example` to `.env` and set at least
|
|
`CKB_REPO_URL`, `CKB_MCP_PUBLIC_URL` and the auth settings (step 3). That
|
|
file explains every setting.
|
|
3. **Start it** with `docker compose -f compose.example.yaml up -d --build`
|
|
from the `server/` folder, or run `server.py` under systemd with the same
|
|
environment.
|
|
4. **Put a reverse proxy in front** (Caddy, Traefik, nginx) for HTTPS. In token
|
|
mode, switch off the proxy's access log for this host, because the token is
|
|
part of the URL. The server answers only to the host in
|
|
`CKB_MCP_PUBLIC_URL` and to loopback (protection against DNS rebinding).
|
|
If the proxy passes a different `Host` header, list the names in
|
|
`CKB_MCP_ALLOWED_HOSTS`; `*` turns the check off.
|
|
5. **Check it:** `https://<host>/health` should answer `{"status":"ok",...}`.
|
|
|
|
---
|
|
|
|
## 3. Choose how people sign in
|
|
|
|
One setting, `CKB_MCP_AUTH`, decides. You can change it later and restart, and
|
|
nothing else needs to change.
|
|
|
|
| Mode | Good for | How it works |
|
|
|---|---|---|
|
|
| `token` | you alone, a few people, agents | A long secret. Claude's web app uses it in the URL: `https://<host>/<token>/mcp`. Other clients send it as `Authorization: Bearer <token>`. One read-write token (`CKB_MCP_TOKEN`), one read-only token (`CKB_MCP_READ_TOKEN`), or a file with one token per person or agent |
|
|
| `oauth` | a team | People sign in through your identity provider (Authentik, Keycloak, Zitadel, Auth0, Entra ID...). You list who may connect and who may write, by email or `@domain` |
|
|
| `none` | local stdio only | The server refuses to run this way on a public address |
|
|
|
|
**Read-only access.**
|
|
- With tokens: use `CKB_MCP_READ_TOKEN`, or leave out `"write": true` for that
|
|
person in the tokens file.
|
|
- With OAuth: anyone not on `CKB_MCP_OAUTH_WRITERS` is read-only. An agent with
|
|
no email can be made read-only with the `CKB_MCP_OAUTH_WRITE_SCOPE` scope.
|
|
- With OAuth, an email counts only when the identity provider marks it
|
|
verified (`email_verified`). If yours never sends that (Entra ID access
|
|
tokens), set `CKB_MCP_OAUTH_TRUST_EMAIL=1`.
|
|
- Either way, read-only users don't even see the write tools.
|
|
|
|
Treat a token URL like a password. To revoke one, change the token and
|
|
restart; the old URL stops working.
|
|
|
|
---
|
|
|
|
## 4. Connect Claude
|
|
|
|
- **Claude web/desktop/mobile:** Settings → Connectors → *Add custom
|
|
connector*. In token mode, paste `https://<host>/<token>/mcp`. In OAuth mode,
|
|
paste `https://<host>/mcp`; Claude finds your identity provider on its own.
|
|
If the provider doesn't support automatic client registration, create a
|
|
client there and enter its ID and secret under *Advanced settings*.
|
|
Anthropic's connector documentation lists the redirect URI to allow.
|
|
- **Claude Code (remote):**
|
|
`claude mcp add --transport http ckb https://<host>/mcp --header "Authorization: Bearer <token>"`
|
|
|
|
On Team and Enterprise plans, an owner may have to allow custom connectors
|
|
first.
|
|
|
|
**Recommended:** in the connector's settings, set the write tools
|
|
(`add_to_inbox`, `withdraw_submission`, `request_retraction`) to *ask before
|
|
use*. Then nothing is written without you approving it in Claude's own dialog.
|
|
|
|
---
|
|
|
|
## 5. Several knowledge bases in one Claude
|
|
|
|
Run **one server per KB**, each with its own clone, URL and access settings,
|
|
and add each as its own connector. `compose.example.yaml` shows two side by
|
|
side. A subdomain per KB (`kb-alpha.example.com`) is the simplest setup.
|
|
|
|
Give each a clear `CKB_MCP_NAME` and a one-line `CKB_MCP_DESCRIPTION`. Every
|
|
tool description starts with the name, so Claude can tell which KB it is
|
|
asking.
|
|
|
|
### How it keeps material out of the wrong KB
|
|
|
|
1. **Every write names its KB.** The server rejects a write whose `kb` doesn't
|
|
match its own name, so material sent to the wrong connector is refused,
|
|
not filed.
|
|
2. **You confirm every write.** If the client supports it, the server asks you
|
|
directly: *"Add “Kickoff notes” to the 'alpha' knowledge base?"*. Otherwise
|
|
Claude gets a question and a confirmation code, and has to ask you before
|
|
it may repeat the call with the code. The code works only for that KB, that
|
|
person and that exact content, and expires after 15 minutes.
|
|
3. **Mistakes can be undone** (see the next section).
|
|
|
|
The confirmation code relies on Claude actually asking you. The *ask before
|
|
use* setting from step 4 is the one gate the model cannot skip, so use it
|
|
whenever more than one KB is connected. `CKB_MCP_CONFIRM=off` is only for a
|
|
KB that never shares a client with another one, or for an automated agent.
|
|
|
|
---
|
|
|
|
## 6. When something went to the wrong KB
|
|
|
|
1. In that KB's connector, ask Claude: *"What have I sent to this KB?"*
|
|
2. **Still pending** (not ingested): *"Withdraw it."* The file is deleted.
|
|
3. **Already ingested:** *"Request its removal, it belongs in project-beta."*
|
|
That files a request in `raw/retractions/`. Only the account that made the
|
|
request can see it.
|
|
4. The KB's maintainer runs a local session. `ckb-ingest` and `ckb-lint` flag
|
|
the request, and `ckb-retract` shows exactly what the source built: pages to
|
|
delete, claims to remove, edges. Nothing is removed until they approve.
|
|
Claims another source also supports are kept.
|
|
5. Add the material to the right KB through its own connector.
|
|
|
|
**What retraction cannot do:** it fixes the KB only as it is now. The content is
|
|
still in git history, on the remote, in every clone and in the server's clone.
|
|
If it was confidential (another client's material, personal data), removing it
|
|
from history is a separate, deliberate history rewrite with a force-push.
|
|
`ckb-retract` explains this but never does it.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause |
|
|
|---|---|
|
|
| Claude says it can't reach the connector | The URL isn't public HTTPS, or the proxy doesn't forward `/mcp` (and, for OAuth, `/.well-known/oauth-protected-resource/...`) |
|
|
| Every request gets `401` | Wrong or rotated token. In OAuth mode, check the server log: a wrong JWKS URL or an unreachable identity provider is logged as `token verification failed` |
|
|
| Claude can read but has no write tools | Your token or account is read-only, or `CKB_MCP_WRITE=off` |
|
|
| A write is refused with *This connector is the 'X' KB...* | Claude chose the wrong connector. Nothing was written |
|
|
| The server won't start: *CKB_MCP_GIT=sync resets ...* | Its clone has local changes or unpushed commits. Give it a clean, dedicated clone |
|
|
| Writes report *nothing was saved - please try again* | The remote kept changing during two attempts. Retry; nothing was left half-done |
|
|
|
|
---
|
|
|
|
*Licensed under the Apache License, Version 2.0 - see [LICENSE](../LICENSE).*
|