Claude Fable 5
d73b120d06
Neues pageListQuerySchema (ISO 8601, Kulanz für Datum ohne Zeit), Query-Parameter auf interner und Public-API-Seitenliste, Prisma-where mit gte; neue Indizes (pondId, createdAt)/(pondId, updatedAt) als Migration. OpenAPI-Parameter, MCP-Parität (list_pages created_since/updated_since), Doku (api-guide, mcp-guide, public-api.md), DB-Test inkl. 400 bei ungültigem Datum. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0155v2aT8AG1kZDQEZiCLBWC
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, created_since?, updated_since?)` | 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.
|