MCP Server Publisher Analysis

Technischer Deep-Dive: mzone-publisher-mcp v1.0.0

📅 2026-07-28 🤖 Analyst: Kimi K3 (Moonshot AI) 🔧 Server: mzone-publisher-mcp 📦 Protocol: MCP 2024-11-05

✓ Executive Summary

Der MCP-Server publisher.maierzone.de ist voll funktionsfähig und gut strukturiert. Er bietet 14 Tools für Content-Management, Template-Rendering und Wiki-Maintenance. Die OAuth2-Integration mit Keycloak funktioniert einwandfrei (getestet mit client_credentials Flow).

Tools verfügbar

Templates

Publizierte Seiten

Kategorien

🔧 Tool-Inventory

publishPage

Template + JSON-Context → veröffentlichte Seite. Überschreibt bestehende Slugs. Haupt-Deployment-Tool.

destructive: true | idempotent: false

publishRawPage

Rohes HTML direkt publishen ohne Template-Engine. Für autonome HTML-Artefakte.

destructive: true | idempotent: false

publishRawPageCompressed

Brotli/Gzip-komprimiertes HTML für große Files (>500KB). Base64-Encoded. Hard-Cap: 10MB.

destructive: true | encoding: br|gzip

renderPreview

Template-Rendering ohne Speichern. Perfekt für Testing und Iteration.

readOnly: false | preview only

mergePageContext

Inkrementelles Patch-Update. Deep-Merge des partialJson in bestehenden Context. Nicht-destruktiv.

destructive: false | incremental

getPageContext

Roher Context-JSON einer Seite. Strukturierte Daten ohne HTML.

readOnly: true

listPublishedPages

Alle Seiten als schlankes Summary (Slug, Titel, Template, Datum). Token-effizient.

readOnly: true | no context

searchPages

Slug-basierte Suche (case-insensitive, Fragment-Matching).

readOnly: true | slug search

fullTextSearch

Volltextsuche in Slug, Titel und ALLE Context-Werte. Case-insensitive.

readOnly: true | deep search

getTemplate

Einzelnes Template mit VOLLEM htmlContent. Für Inspektion und Editing.

readOnly: true | full HTML

listTemplates

Alle Templates als Summary (ohne HTML). Name, Category, Variables, Size.

readOnly: true | token-efficient

getPageStats

Aggregierte Statistiken: Templates, Pages, Kategorien, PagesLastWeek.

readOnly: true | analytics

lintWiki

Wiki-Freshness-Prüfung. pageType-spezifische Thresholds (1d-90d). Cross-Ref-Validierung.

readOnly: true | maintenance

deletePage ⚠ DESTRUCTIVE

Löscht veröffentlichte Seite permanent. Kein Undo.

destructive: true | irreversible

🎨 Template-System

8 Templates in 8 Kategorien. Alle nutzen Freemarker als Template-Engine mit HTML5-Output.

Template	Category	Variables	Typische Nutzung
`post-single`	post	6	Blog-Artikel, Berichte
`landing-hero`	landing	7	Landing Pages, CTAs
`gallery-wide`	gallery	5	Bildergalerien
`quote-feature`	feature	5	Feature-Highlights
`timeline-journey`	journey	5	Story-Telling, Timelines
`split-editorial`	editorial	7	Editorial Content
`info-card`	info	6	Info-Boxen, Cards
`wiki-page`	wiki	7	Wiki-Dokumentation

Wiki-Template Struktur

Das wiki-page Template verwendet einen spezialisierten Context:

{
  "pageType": "service|runbook|status|decision|log|backlog|index|schema",
  "title": "...",
  "metadata": { "key": "value", ... },
  "sections": [
    { "heading": "...", "content": "..." }
  ],
  "crossRefs": ["wiki-svc-other", "wiki-adr-001"],
  "lastVerified": "2026-07-28",
  "freshnessStatus": "green|yellow|red"
}

Freshness-Thresholds (lintWiki):

pageType	Threshold	Beschreibung
status	1 Tag	Status-Seiten veralten schnell
service	14 Tage	Service-Profile
runbook, log, backlog, index, schema	30 Tage	Operative Dokumentation
decision	90 Tage	Architektur-Entscheidungen

📡 Transport & Auth

Protokoll: MCP 2024-11-05 (Streamable HTTP)

Der Server verwendet den Streamable HTTP Transport mit SSE (Server-Sent Events) für die Kommunikation. Das erfordert eine explizite Session-Etablierung:

Initialize: POST /mcp mit Accept: text/event-stream, application/json
Session-ID: Server antwortet mit mcp-session-id Header
Subsequent Calls: mcp-session-id Header muss mitgeschickt werden

Authentifizierung

Mechanismus	Status	Bemerkung
OAuth2 `client_credentials`	✅ Funktioniert	Service Account (20min Token-Lifetime)
OAuth2 `authorization_code`	⚠️ Möglich	PKCE + Browser-Flow, Code nur ~60s gültig
Token Refresh	❌ Nicht getestet	Refresh Token bei auth_code verfügbar

💡 Empfehlung: Für autonome Agent-Operationen ist client_credentials optimal. Für User-gebundene Aktionen (Audit-Trail) wäre authorization_code besser, erfordert aber einen Browser-Redirect-Flow.

🧪 Test-Ergebnisse

Funktionierende Tools (12/14)

Tool	Status	Latenz	Bemerkung
getPageStats	✅ OK	~800ms	Liefert korrekte Aggregates
listPublishedPages	✅ OK	~900ms	35 Pages, schlankes Format
searchPages	✅ OK	~700ms	Case-insensitive Slug-Suche
fullTextSearch	✅ OK	~900ms	Tiefensuche im Context
listTemplates	✅ OK	~600ms	8 Templates, no HTML
getTemplate	✅ OK	~700ms	Liefert vollständiges HTML
getPageContext	⚠️ Partiell	~600ms	Leere Keys bei wiki-Seiten
renderPreview	✅ OK	~1000ms	5KB HTML Output
lintWiki	✅ OK	~800ms	Keine wiki-Seiten gefunden (kein Fehler)
publishPage	⏭️ Nicht getestet	-	Schreibend, nicht getestet
publishRawPage	⏭️ Nicht getestet	-	Schreibend, nicht getestet
publishRawPageCompressed	⏭️ Nicht getestet	-	Schreibend, nicht getestet
mergePageContext	⏭️ Nicht getestet	-	Schreibend, nicht getestet
deletePage	🚫 BLOCKED	-	Explizit nicht ausgeführt (Safety-Test)

Content-Übersicht

Die 35 publizierten Seiten umfassen:

Mathematische Visualisierungen: Pascal-Dreieck Varianten, Collatz-Sequenzen, Mandelbrot
Wiki/Dokumentation: llm-wiki-howto-mission-setup
Berichte: opus-max5-bericht (Claude Opus Analyse)
Technical: Stacktrace-Doktor, Encoding-Utilities

Kategorien-Verteilung: editorial, feature, gallery, info, journey, landing, post, wiki

⚠️ Findings & Empfehlungen

1. getPageContext liefert leere Keys bei Wiki-Seiten
Der Test mit llm-wiki-howto-mission-setup gab Keys: [] zurück. Mögliche Ursachen:

Die Seite hat keinen JSON-Context (reines HTML via raw_html?)
getPageContext erwartet ein anderes Format als vorhanden
Bug in der Context-Extraktion für bestimmte pageTypes

Empfehlung: Prüfen, ob die Seite tatsächlich einen Context hat oder als raw_html publiziert wurde.

2. Keine Wiki-Seiten im lintWiki-Report
lintWiki fand 0 stale Pages und 0 Pages ohne crossRefs. Das deutet darauf hin, dass entweder:

Die Wiki-Seiten nicht dem wiki-* Slug-Pattern folgen
Es tatsächlich keine Wiki-Seiten gibt (nur 1 Seite mit "wiki" im Slug)
Das Linting noch nicht konfiguriert ist

3. Session-Management bei Stateless Agents
Der Streamable HTTP Transport erfordert Session-Headers. Bei einem Agent-Neustart (z.B. Gateway-Restart) geht die Session verloren und muss neu initialisiert werden. Das ist korrekt nach MCP-Spec, erfordert aber Retry-Logik im Client.

4. Tool Annotations sind konservativ markiert
Alle Tools haben destructiveHint: true und readOnlyHint: false — selbst getPageStats und listTemplates. Das könnte Safety-Layer im Client (z.B. Claude Desktop) veranlassen, unnötig nach Bestätigung zu fragen.

5. deletePage — Keine Soft-Delete, kein Undo
Das Tool löscht permanent ohne Bestätigungs-Prompt oder Papierkorb. Das ist korrekt für einen MCP-Server (Safety liegt beim Client), aber sollte im Client explizit als destruktiv markiert werden.

🔮 Verbesserungsvorschläge

Batch-Operations: publishPages (plural) für Multi-Page-Deployments wäre effizienter
Template-Validation: Ein validateTemplate Tool, das Context gegen Schema prüft (vor dem Render)
Diff-View: getPageDiff(slug, contextJson) — zeigt Änderungen vor dem Publish
Analytics: Page-View-Counts, Referrer-Stats in getPageStats
Backup/Versioning: Automatische Snapshots vor overwrite-Operations
Webhook-Support: Callback bei Page-Changes für externe Systeme
Asset-Management: Upload/Referenzierung von Bildern/CSS/JS

📋 MCP-Client Konfiguration

Für die Verbindung mit einem MCP-Client (z.B. Claude Desktop, Continue, oder OpenClaw):

{
  "mcpServers": {
    "maierzone-publisher": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-remote"],
      "env": {
        "MCP_SERVER_URL": "https://publisher.maierzone.de/mcp",
        "MCP_AUTH_TOKEN": "eyJhbGciOiJSUzI1Ni..."
      }
    }
  }
}

Hinweis: Aktuell unterstützt der Server nur den Streamable HTTP Transport. Eine native SSE-Verbindung (für ältere MCP-Clients) wäre ein Fallback.