Architektur

Systemübersicht

KI-Assistent (Chat-Oberfläche)
    |
    v (Natural Language)
TypingMind MCP Proxy (mcp-vps.satware.ai)
    |
    v (MCP Protocol via stdio)
Docker Container (git.satware.ai/satware.ai/mcp-dokuwiki:vX.Y.Z)
    |
    v (JSON-RPC API)
DokuWiki-Instanz (lib/exe/jsonrpc.php)

Komponenten

MCP Server

Node.js 22 (ESM). stdio-Transport. 48 Tools über Factory-Pattern registriert.

DokuWiki Client

JSON-RPC Client mit Retry-Logik (exponentieller Backoff), Bearer-Token-Auth.

Docker Container

node:22-alpine (Multi-Stage-Build). Pro Sitzung gestartet, wird beim Beenden entfernt.

MCP Proxy

@typingmind/mcp auf mcp-vps.satware.ai. Startet Container, leitet stdio weiter.

Transport: stdio

Der Server verwendet ausschließlich stdio-Transport (StdioServerTransport aus dem MCP SDK). Es gibt keinen HTTP/SSE-Endpunkt.

stdout: reserviert für MCP JSON-RPC Protokoll (niemals Logs)
stderr: JSON-Logging (logger.js schreibt nur nach stderr)

Der TypingMind MCP Proxy startet den Docker-Container mit docker run -i --rm und kommuniziert über stdin/stdout.

Tool-Architektur

Alle 48 Tools folgen dem Factory-Pattern:

export function toolName(dokuwikiClient, config) {
  return {
    name: 'dokuwiki_tool_name',
    description: '...',
    inputSchema: { type: 'object', properties: {...} },
    handler: async (args) => { ... }
  };
}

Tools werden in src/tools/index.js registriert. Jede Tool-Factory erhält den DokuWikiClient und die Server-Konfiguration.

Tool-Kategorien

Kategorie	Tools	Beschreibung
Seitenverwaltung	22	get, save, update, search, list, info, history, links, backlinks, lock, unlock
Medien	8	upload, download, list, info, delete, history, usage
Struct	4	get/save data, get schema, aggregation
Move	2	rename page, rename media (mit Backlink-Updates)
ACL	3	list, add, delete ACL-Regeln
Benutzer	2	create, delete users
Audit	6	orphans, stale, duplicates, tag consistency, link check
Discovery	1	get_wiki_capabilities

11 Tools sind als destruktiv markiert (destructiveHint: true) und werden im MCP-Protokoll entsprechend gekennzeichnet.

Sicherheitsmerkmale

Feature	Implementierung
Auth	JWT Bearer Token (`Authorization: Bearer <token>`)
Retry	Exponentieller Backoff (3 Versuche, max 5)
Rate Limiting	Pro-Kategorie-Limit
Logging	JSON nach stderr (strukturiert)
Fehlerbehandlung	`DokuWikiRequestError` mit `rpcCode`/`httpStatus`/`errorType`
Größenschutz	Size-Delta-Guard für `save_page`/`update_page` (mode=replace): lehnt Inhalte ab, die unter 50% der bisherigen Seitengröße haben (bei Seiten über 2000 Bytes)

Versionierung

Die Version wird zur Laufzeit ermittelt (Single Source of Truth):

src/build-info.json (in CI generiert aus git describe)
Fallback: git describe --tags --always --dirty
Fallback: package.json version

Keine hartcodierten Versionsstrings im Quellcode. semantic-release erstellt Tags automatisch aus Conventional Commits.