Wiki.js MCP Server: Technische Details

Technische Details des Wiki.js MCP Servers: Aufbau, verwendete GraphQL-Operationen, Ablauf eines Updates, Fehlerbehandlung, Beenden und Entwicklung.

English version

Zurück zur Übersicht

Technische Details

Aufbau

Pfad	Aufgabe
`src/index.ts`	Einstiegspunkt: lädt die `.env`, prüft die Variablen, registriert die 7 Tools, startet den stdio-Transport, behandelt Signale
`src/constants.ts`	feste Limits (Timeout, Kürzung, Größen, Paginierung)
`src/schemas/index.ts`	Zod-Schemas für alle Tool-Eingaben
`src/services/client.ts`	`WikiJsClient`: sendet die GraphQL-Anfragen
`src/services/error-handler.ts`	einheitliche Fehler- und Erfolgsantworten
`src/tools/*.ts`	je eine Datei pro Tool
`tests/update-page.test.ts`	Vitest-Tests für das Update-Verhalten

Das Paket ist ein ES-Modul ("type": "module"), Einstiegspunkt und bin-Eintrag ist dist/index.js.

Technologien

TypeScript, kompiliert mit tsc nach dist/
MCP SDK @modelcontextprotocol/sdk (McpServer, stdio-Transport)
Zod für die Eingabevalidierung
dotenv zum Laden der .env
Vitest für Tests
HTTP über das in Node.js eingebaute fetch, keine zusätzliche HTTP-Bibliothek

Verwendete GraphQL-Operationen

Alle Anfragen gehen als POST mit JSON-Body und Authorization: Bearer <Token> an WIKIJS_API_URL.

Tool	Operation	Hinweis
`wikijs_list_pages`	`pages.list`	liefert alle Seiten, Locale-Filter und Paginierung passieren im Server
`wikijs_get_page`	`pages.single(id)` oder `pages.singleByPath(path, locale)`	ohne Tags
`wikijs_search_pages`	`pages.search(query)`	Locale-Filter im Server
`wikijs_create_page`	`pages.create`	mit `path`, `title`, `content`, `description`, `editor`, `isPublished`, `isPrivate`, `locale`, `tags`
`wikijs_update_page`	`pages.update`	mit `id`, `content`, `title`, `description`, `isPublished`, `tags`
`wikijs_delete_page`	`pages.delete(id)`
`wikijs_move_page`	`pages.move(id, destinationPath, destinationLocale)`

Pfadbasierte Aufrufe von update, delete und move lösen den Pfad zuerst mit pages.singleByPath in eine ID auf.

Ablauf von wikijs_update_page

sequenceDiagram
    participant C as MCP-Client
    participant S as MCP-Server
    participant W as Wiki.js

    C->>S: wikijs_update_page
    S->>S: Zod-Validierung
    S->>W: singleByPath wenn nur path
    S->>W: single(id) wenn content, title oder description fehlt
    S->>W: list wenn tags fehlt
    S->>W: update mit allen Feldern
    W-->>S: responseResult
    S-->>C: success oder Fehler

Die Mutation pages.update benötigt einen Wert für Titel, Beschreibung, Inhalt und Tags; deshalb ergänzt der Server fehlende Felder aus dem aktuellen Stand der Seite.

Fehlerbehandlung

Jeder Tool-Handler fängt Fehler und gibt isError: true mit {"success": false, "error": ..., "tool": ...} zurück. Der Server stürzt dabei nicht ab.
Validierungsfehler nennen das Feld und den Grund.
HTTP-Status außerhalb von 2xx ergibt Wiki.js API request failed: HTTP error! status: <Code>.
GraphQL-Fehler ergeben Wiki.js API request failed: GraphQL request failed: <Meldungen>.
Meldet Wiki.js im responseResult succeeded: false, lautet die Meldung Failed to create page: ..., Failed to update page: ..., Failed to delete page: ... oder Failed to move page: ... mit dem Text von Wiki.js.
Überschreitet eine Anfrage 30 Sekunden, kommt Request timed out. Please try again.
Der Server wiederholt keine Anfragen automatisch.

Beenden

Bei SIGINT, SIGTERM, unbehandelten Fehlern und Promise-Rejections schließt der Server die MCP-Verbindung und beendet sich. Ein EPIPE (Client hat die Verbindung geschlossen) wird dabei nicht geloggt.

Entwicklung

npm install
npm run dev         # tsx im Watch-Modus
npm run build       # Kompilieren nach dist/
npm run typecheck   # Typprüfung ohne Ausgabe
npm test            # Vitest

Die CI baut und typprüft das Projekt mit Node.js 18, 20 und 22.