Claude Fable 5
eeb0ef6794
All checks were successful
CD / Build and push images (push) Successful in 1m9s
CD / Deploy to Test (push) Successful in 10s
CD / Smoke tests against Test (push) Successful in 1m10s
CD / Promote to Int (push) Successful in 11s
CI / Lint, typecheck, test (push) Successful in 4m7s
CI / Build container images (push) Has been skipped
CI / Auth e2e pack (push) Successful in 5m34s
CI / Import/export fidelity gate (push) Successful in 47s
Seven audience-targeted documents (English first, German translation to follow), linked from the README and a new docs/manual/ index: - docs/features.md — public-facing feature overview: what Dorfteich can do and why that matters - docs/manual/user-guide.md — everyday use: editor, wikilinks, labels, search, comments, watches/digests, import/export, settings - docs/manual/pond-admin-guide.md — pond configuration: members/roles, access rules incl. label scoping and public pages, labels, comment policy, plugins, API/MCP opt-ins, files, export - docs/manual/site-admin-guide.md — instance administration: wizard, settings, quotas, uploads, API/MCP switches, legal pages, plugins, users, and the system panel (jobs/backups/audit/storage) - docs/manual/api-guide.md — example-driven public-API walkthrough (tokens, reading, writing through the collab-safe path, labels, comments, error semantics) - docs/manual/mcp-guide.md — connecting AI assistants: switches, token scopes, Claude Code one-liner, mcp-remote bridge, tool table, audit and safety properties - docs/developer/extending.md — plugin development (sandbox contract, SDK, block plugins, bundled apps/fullscreen, shipping) and core contributions (stack, dev environment, gates, house rules) README: documentation index, repository-layout rows for docs/manual and docs/developer, and the stale "architecture phase" status brought up to reality. All relative links verified. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# MCP guide — connecting your AI to Dorfteich
|
|
|
|
Dorfteich ships its own [MCP](https://modelcontextprotocol.io) endpoint
|
|
at `/api/mcp` (Streamable HTTP). Any MCP-capable assistant — Claude
|
|
Code, Claude Desktop via a bridge, and others — can search, read, and
|
|
(if you allow it) write your wiki, with **exactly your permissions**.
|
|
There is no extra server to run: the endpoint is part of the instance.
|
|
|
|
## Switching it on
|
|
|
|
Like the REST API, MCP is **off by default** and has its **own,
|
|
independent switches**:
|
|
|
|
1. **Site admin**: Admin → Settings → Public API → "Enable the built-in
|
|
MCP endpoint".
|
|
2. **Each pond** that the assistant should see: pond settings → "Expose
|
|
this pond to AI assistants (MCP)".
|
|
|
|
A pond without the opt-in is invisible to MCP clients — even to your own
|
|
token.
|
|
|
|
## Get a token
|
|
|
|
MCP uses the same **personal access tokens** as the REST API: create one
|
|
under **Settings → API tokens**. Pick the scope deliberately:
|
|
|
|
- `read` — the assistant can list, read, and search, nothing else.
|
|
- `read+write` — it may also create/update pages, comment, and set
|
|
labels.
|
|
|
|
Consider restricting the token to the specific pond(s) you want the
|
|
assistant to work in.
|
|
|
|
## Connect Claude Code
|
|
|
|
```sh
|
|
claude mcp add --transport http dorfteich https://wiki.example.com/api/mcp \
|
|
--header "Authorization: Bearer dt_pat_..."
|
|
```
|
|
|
|
That's it — Claude Code lists the tools on the next start. Stdio-only
|
|
clients bridge with `mcp-remote`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"dorfteich": {
|
|
"command": "npx",
|
|
"args": [
|
|
"mcp-remote",
|
|
"https://wiki.example.com/api/mcp",
|
|
"--header",
|
|
"Authorization: Bearer dt_pat_..."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## What the assistant can do
|
|
|
|
| Tool | Does |
|
|
| -------------------------------------------- | ------------------------------------------- |
|
|
| `list_ponds` | the ponds this token can reach |
|
|
| `list_pages(pond)` | pages with slug, title, labels, timestamps |
|
|
| `read_page(pond, page)` | a page as Markdown plus metadata |
|
|
| `search(query, pond?, label?)` | full-text search with snippets |
|
|
| `create_page(pond, title, markdown)` | new page from Markdown _(write)_ |
|
|
| `update_page(pond, page, markdown?, title?)` | rename and/or replace content _(write)_ |
|
|
| `add_comment(pond, page, text)` | comment on a page _(write)_ |
|
|
| `list_labels(pond)` | the pond's label tree |
|
|
| `set_page_labels(pond, page, labelIds)` | replace a page's labels _(write)_ |
|
|
| `export_pond(pond)` | a download link for the Markdown-ZIP export |
|
|
|
|
Content updates travel the same collaborative path as human edits: open
|
|
editors converge live, and the previous state stays in the version
|
|
history — an AI edit can always be reviewed and reverted like any other
|
|
change.
|
|
|
|
## Good to know
|
|
|
|
- **Permissions are yours.** The assistant sees precisely the pages your
|
|
account may read; label-scoped rules, public/private, everything
|
|
applies unchanged.
|
|
- **Every write is audit-logged** with the token attributed — the site
|
|
admin's audit viewer shows what the assistant changed.
|
|
- **Rate-limited** per token; a runaway agent gets `429`, not a melted
|
|
instance.
|
|
- **Stateless**: each request stands alone; revoking the token under
|
|
Settings → API tokens cuts the assistant off immediately.
|
|
- The endpoint speaks MCP over Streamable HTTP (POST). GET/SSE session
|
|
resumption is not offered — clients fall back to plain request/response,
|
|
which every current client supports.
|
|
|
|
## A sensible first session
|
|
|
|
Ask your assistant to `list_ponds`, then `search` for something you know
|
|
is there, `read_page` it, and — with a write token — draft a new page.
|
|
Check the page's version history afterwards: you will find the
|
|
assistant's edit as a normal, restorable version.
|