dorfteich/docs/de/manual/mcp-guide.md

MCP-Handbuch — deine KI mit Dorfteich verbinden

Englisches Original: docs/manual/mcp-guide.md

Dorfteich bringt seinen eigenen MCP- Endpoint unter /api/mcp mit (Streamable HTTP). Jeder MCP-fähige Assistent — Claude Code, Claude Desktop über eine Bridge und andere — kann dein Wiki durchsuchen, lesen und (wenn du es erlaubst) beschreiben, mit exakt deinen Berechtigungen. Es läuft kein zusätzlicher Server: Der Endpoint ist Teil der Instanz.

Einschalten

Wie die REST-API ist MCP standardmäßig aus und hat eigene, unabhängige Schalter:

1. Site-Admin: Admin → Einstellungen → Öffentliche API → „Eingebauten MCP-Endpoint aktivieren".
2. Jeder Teich, den der Assistent sehen soll: Teich-Einstellungen → „Diesen Teich für KI-Assistenten freigeben (MCP)".

Ein Teich ohne Freigabe ist für MCP-Clients unsichtbar — selbst für dein eigenes Token.

Ein Token besorgen

MCP nutzt dieselben persönlichen API-Tokens wie die REST-API: Lege eins unter Einstellungen → API-Tokens an. Wähle den Scope bewusst:

• read — der Assistent kann auflisten, lesen und suchen, sonst nichts.
• read+write — er darf zusätzlich Seiten anlegen/ändern, kommentieren und Labels setzen.

Erwäge, das Token auf genau die Teiche zu beschränken, in denen der Assistent arbeiten soll.

Claude Code verbinden

claude mcp add --transport http dorfteich https://wiki.example.com/api/mcp \
  --header "Authorization: Bearer dt_pat_..."

Das war's — Claude Code listet die Tools beim nächsten Start. Reine Stdio-Clients überbrücken mit mcp-remote:

{
  "mcpServers": {
    "dorfteich": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://wiki.example.com/api/mcp",
        "--header",
        "Authorization: Bearer dt_pat_..."
      ]
    }
  }
}

Was der Assistent kann

Tool	Tut
list_ponds	die Teiche, die dieses Token erreicht
list_pages(pond)	Seiten mit Slug, Titel, Parent, Labels
read_page(pond, page)	eine Seite als Markdown plus Metadaten
search(query, pond?, label?)	Volltextsuche mit Snippets
create_page(pond, title, markdown, parent?)	neue Seite aus Markdown (write)
update_page(pond, page, markdown?, title?, parent?)	umbenennen, Inhalt ersetzen, verschieben (write)
add_comment(pond, page, text)	eine Seite kommentieren (write)
list_labels(pond)	der Label-Baum des Teichs
set_page_labels(pond, page, labelIds)	die Labels einer Seite ersetzen (write)
export_pond(pond)	ein Download-Link für den Markdown-ZIP-Export

Inhalts-Updates nehmen denselben kollaborativen Weg wie menschliche Bearbeitungen: Offene Editoren konvergieren live, und der vorherige Stand bleibt im Versionsverlauf — eine KI-Änderung lässt sich immer wie jede andere Änderung prüfen und zurücknehmen.

Gut zu wissen

• Die Berechtigungen sind deine. Der Assistent sieht genau die Seiten, die dein Konto lesen darf; Label-Regeln, öffentlich/privat — alles gilt unverändert.
• Jeder Schreibzugriff wird audit-geloggt, dem Token zugeordnet — im Audit-Log des Site-Admins steht, was der Assistent geändert hat.
• Rate-limitiert pro Token; ein außer Kontrolle geratener Agent bekommt 429, keine geschmolzene Instanz.
• Zustandslos: Jede Anfrage steht für sich; das Widerrufen des Tokens unter Einstellungen → API-Tokens schneidet den Assistenten sofort ab.
• Der Endpoint spricht MCP über Streamable HTTP (POST). GET/SSE- Session-Resumption wird nicht angeboten — Clients fallen auf reines Request/Response zurück, was jeder aktuelle Client unterstützt.

Eine sinnvolle erste Sitzung

Bitte deinen Assistenten um list_ponds, dann search nach etwas, von dem du weißt, dass es da ist, read_page darauf — und mit einem Write-Token: eine neue Seite entwerfen. Sieh dir danach den Versionsverlauf der Seite an: Du findest die Änderung des Assistenten als normale, wiederherstellbare Version.