# MCP-Handbuch — deine KI mit Dorfteich verbinden

_Englisches Original: [docs/manual/mcp-guide.md](../../manual/mcp-guide.md)_

Dorfteich bringt seinen eigenen [MCP](https://modelcontextprotocol.io)-
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

```sh
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`:

```json
{
  "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, created_since?, updated_since?)`    | 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.