Claude Fable 5
ffcc337ed0
Some checks failed
CD / Build and push images (push) Successful in 3m57s
CD / Deploy to Test (push) Successful in 9s
CI / Lint, typecheck, test (push) Failing after 4m16s
CI / Auth e2e pack (push) Has been skipped
CI / Import/export fidelity gate (push) Has been skipped
CI / Build container images (push) Has been skipped
CD / Smoke tests against Test (push) Successful in 1m19s
CD / Promote to Int (push) Successful in 11s
The slug-based machine surfaces now see and shape the hierarchy: - REST: page list/detail carry parent (the parent page's slug, nulled when the token's user may not read it — same no-leak rule as the internal list); create accepts parent; PATCH accepts parent (slug nests, null moves to the top level, appended at the end of the new sibling group via the new PagesService.moveToEnd). Cycle/depth refusals keep their regular error codes. OpenAPI updated. - MCP: list_pages returns parent, create_page takes an optional parent slug, update_page moves with parent (slug|null); tool errors carry the api code (page_cycle covered in the e2e pack). - ZIP export deliberately stays flat — noted in features.md; the hierarchy is organizational only. e2e: REST pack covers nested create, list shape, move/root-move, 409 page_cycle, 404 unknown parent; MCP pack covers nested create, list parent, and the cycle tool error. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# MCP guide — connecting your AI to Dorfteich
|
|
|
|
_Deutsche Fassung: [docs/de/manual/mcp-guide.md](../de/manual/mcp-guide.md)_
|
|
|
|
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, parent, labels |
|
|
| `read_page(pond, page)` | a page as Markdown plus metadata |
|
|
| `search(query, pond?, label?)` | full-text search with snippets |
|
|
| `create_page(pond, title, markdown, parent?)` | new page from Markdown _(write)_ |
|
|
| `update_page(pond, page, markdown?, title?, parent?)` | rename, replace content, move _(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.
|