Architecture

System Overview

AI Assistant (Chat Interface)
    |
    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 Instance (lib/exe/jsonrpc.php)

Components

MCP Server

Node.js 22 (ESM). stdio transport. 48 tools registered via factory pattern.

DokuWiki Client

JSON-RPC client with retry logic (exponential backoff), Bearer token auth.

Docker Container

node:22-alpine (multi-stage build). Spawned per session, auto-removed on exit.

MCP Proxy

@typingmind/mcp on mcp-vps.satware.ai. Spawns container, forwards stdio.

Transport: stdio

The server uses exclusively stdio transport (StdioServerTransport from the MCP SDK). There is no HTTP/SSE endpoint.

• stdout: reserved for MCP JSON-RPC protocol (never logs)
• stderr: JSON logging (logger.js writes only to stderr)

The TypingMind MCP Proxy spawns the Docker container with docker run -i --rm and communicates via stdin/stdout.

Tool Architecture

All 48 tools follow the factory pattern:

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

Tools are registered in src/tools/index.js. Each tool factory receives the DokuWikiClient and server configuration.

Tool Categories

Category	Tools	Description
Page Management	22	get, save, update, search, list, info, history, links, backlinks, lock, unlock
Media	8	upload, download, list, info, delete, history, usage
Struct	4	get/save data, get schema, aggregation
Move	2	rename page, rename media (with backlink updates)
ACL	3	list, add, delete ACL rules
Users	2	create, delete users
Audit	6	orphans, stale, duplicates, tag consistency, link check
Discovery	1	get_wiki_capabilities

11 tools are marked as destructive (destructiveHint: true) and are flagged accordingly in the MCP protocol.

Security Features

Input Validation

All tool inputs are validated: path traversal protection, namespace validation, media name validation, size limits (1MB pages, 10MB media).

Feature	Implementation
Auth	JWT Bearer Token (Authorization: Bearer <token>)
Retry	Exponential backoff (3 attempts, max 5)
Rate Limiting	Per-category limits
Logging	JSON to stderr (structured)
Error Handling	DokuWikiRequestError with rpcCode/httpStatus/errorType
Size Guard	Size-delta guard for save_page/update_page (mode=replace)

Versioning

The version is determined at runtime (single source of truth):

1. src/build-info.json (generated in CI from git describe)
2. Fallback: git describe --tags --always --dirty
3. Fallback: package.json version

No hardcoded version strings in source code. semantic-release creates tags automatically from Conventional Commits.