Wiki.js Plugin: Technik

Technische Details des Wiki.js Plugins: Aufbau, Startablauf, GraphQL-Client, SQLite-Schema für Historie und verified-Marker, Validierung, Schrumpf-Schutz und bekannte Eigenheiten.

English Version

Zurück zur Übersicht

Wiki.js Plugin: Technik

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Aufbau

wikijs-plugin/
├── .claude-plugin/            plugin.json und marketplace.json
├── .mcp.json                  Registrierung des MCP-Servers wikijs-mcp
├── bin/                       run-server (POSIX) und run-server.cmd (Windows)
├── servers/wikijs-mcp-server/
│   ├── run.py                 Einstiegspunkt
│   ├── server.py              Tool-Registrierung
│   └── tools/                 client, pages, validation, config, db, history
└── skills/                    docs-wiki, source-check, translation-check, setup

Das Plugin hat keine Hooks. Der MCP-Server läuft über den Standard-Transport stdio und nutzt mcp[cli] (Version 2.x), httpx und python-dotenv.

Architektur

graph TD
    A["Claude Code"] --> B["MCP-Server wikijs-mcp"]
    B --> C["Validierung"]
    C --> D["WikiJsClient (httpx)"]
    D --> E["Wiki.js GraphQL API"]
    B --> F["Historie (SQLite)"]
    G["Skills"] --> B

Baustein	Aufgabe
`server.py`	Registriert die zehn Tools samt Annotations, baut den Client erst beim ersten Aufruf
`tools/pages.py`	Geschäftslogik: Validierung, Auflösen von Pfad zu ID, Schrumpf-Schutz, Historie
`tools/client.py`	GraphQL-Client mit Bearer-Token, 30 Sekunden Zeitlimit, Kürzung großer Inhalte
`tools/validation.py`	Eingabegrenzen
`tools/config.py`	Zugangsdaten laden
`tools/db.py`, `tools/history.py`	SQLite-Schema, Historie und verified-Marker

Startablauf

sequenceDiagram
    participant C as Claude Code
    participant R as bin/run-server
    participant S as run.py
    participant W as Wiki.js

    C->>R: Server starten
    R->>S: Python aus ~/.wikijs-plugin/venv
    S->>S: Zugangsdaten prüfen, sonst Abbruch
    C->>S: Tool-Aufruf
    S->>S: Client beim ersten Aufruf anlegen
    S->>W: GraphQL-Anfrage
    W-->>S: Antwort
    S-->>C: Ergebnis

Der Wrapper bin/run-server startet den Python-Interpreter aus ~/.wikijs-plugin/venv/, unter Windows macht das bin/run-server.cmd. run.py prüft die Zugangsdaten vor dem Start und beendet sich mit Fehlermeldung, wenn sie fehlen.

GraphQL-Zugriff

Tool	Wiki.js-Operation
`wikijs_list_pages`	`pages.list`, Filter und Ausschnitt lokal
`wikijs_get_page`	`pages.single` (per ID) oder `pages.singleByPath`
`wikijs_search_pages`	`pages.search`, Locale-Filter lokal
`wikijs_create_page`	`pages.create`
`wikijs_update_page`	`pages.update`, vorher Seite laden und bei fehlenden Tags die Seitenliste
`wikijs_delete_page`	`pages.delete`
`wikijs_move_page`	`pages.move`

Wiki.js-Fehler (succeeded: false) werden zu Tool-Fehlern mit der Meldung von Wiki.js.

Lokale Datenbank

Datei: ~/.wikijs-plugin/wikijs-plugin.db (SQLite, WAL-Modus). Das Schema wird beim ersten echten Zugriff angelegt.

Tabelle page_history:

Spalte	Inhalt
`id`	Laufende Nummer
`page_path`	Seitenpfad
`locale`	Sprache
`changed_at`	Zeitstempel (UTC)
`source_repo`	Quellprojekt
`source_ref`	Commit oder Tag
`summary`	Kurznotiz
`verified`	`1` nur bei Einträgen von `wikijs_mark_verified`, sonst `0`
`page_updated_at`	`updatedAt` der Seite zum Zeitpunkt der Prüfung

Ein Index auf (page_path, locale, changed_at) beschleunigt die Abfragen. Der Schema-Stand liegt in PRAGMA user_version, ältere Dateien werden beim Zugriff migriert.

Geschrieben bei: wikijs_create_page und wikijs_update_page loggen einen Eintrag, wenn mindestens eines von sourceRepo, sourceRef, summary gesetzt ist. Der Ref bedeutet nur, dass die Seite bei diesem Stand geschrieben wurde.
Verifiziert bei: Nur wikijs_mark_verified setzt verified = 1. wikijs_get_verified_refs liefert je Seite und Sprache den jüngsten solchen Eintrag. Spätere unverifizierte Schreibvorgänge verdecken ihn nicht.
Pro Rechner: Die Datei liegt lokal, es gibt keine Synchronisation. Auf einem anderen Rechner gelten dieselben Seiten als unverifiziert.
Fehlertoleranz: Scheitert das Loggen (z. B. gesperrte Datenbank), bleibt die bereits geschriebene Wiki.js-Seite gültig, die Meldung geht auf stderr. Beim Öffnen wird bei gesperrter Datenbank bis zu fünfmal wiederholt. Liegt die Datei auf einem Netzwerk- oder Cloud-Sync-Pfad, ist das Zeitlimit 30 statt 5 Sekunden.
Pfad-Schlüssel: Historie und Marker hängen am Pfad, nicht an der Seiten-ID. Nach wikijs_move_page bleiben sie beim alten Pfad.

Bekannte Eigenheiten

Eigenheit	Auswirkung
`isPublished` wird bei Updates nicht aus der Seite übernommen	Ohne `isPublished: true` wird eine veröffentlichte Seite zum Entwurf
Gekürzter Inhalt bei Seiten über 100.000 Zeichen	Ein Update ohne `content` (oder mit dem gelesenen Text) schreibt die gekürzte Fassung zurück
Der Kürzungshinweis nennt Pfad-Zugriff als Ausweg	Auch der Pfad-Zugriff kürzt
`wikijs_list_pages` und Updates ohne `tags` laden alle Seiten	Bei großen Wikis spürbar langsam
Beschreibung bis 500 Zeichen erlaubt	Die Wiki.js-Datenbank begrenzt in der Praxis auf 255
Pfad-Validierung ohne Punkt und Nicht-ASCII	Solche Seiten nur per `id` ansprechbar

Weitere Hinweise zu Fehlerbildern: Fehlerbehebung. Zum Umgang mit Token und Daten: Datenschutz und Sicherheit.