mzone-publisher — MCP-Werkzeuge

43 Werkzeuge, erzeugt beim Start aus den @McpTool-Annotationen

backlogGet

Liest ein einzelnes Ticket vollstaendig: den ungekappten Rumpf und alle Kommentare als Markdown-Rohtext, in Erstellreihenfolge. Der Gegenpart zu backlogQuery, deren Rumpf bei 1200 Zeichen endet.

backlogQuery

Liest Tickets aus dem Backlog-Cockpit (/admin/backlog). filterJson ist optional und kennt: status[] (IDEA|READY|DOING|REVIEW|DONE|DROPPED), type[] (STORY|BUG|CHORE|SPIKE), priority[] (P0..P3), epic, assignee, text (sucht in Key, Titel, Rumpf), limit (Vorgabe 50, hoechstens 200), compact (true = ohne Rumpf, Kompaktmodus gegen das Token-Limit), fields (kommagetrennte Feldnamen, z.B. "key,title,status"; erlaubt: key, title, type, status, priority, epicKey, assignee, labels, wikiSlug, ageDays, createdAt, closedAt, body, bodyTruncated, commentCount; leere Felder fehlen in der Antwort immer). Weggelassene Filter schraenken nicht ein. Sortiert nach Prioritaet, dann Alter. Jedes Ticket traegt seinen Rumpf, gekappt bei 1200 Zeichen (bodyTruncated sagt es an); den vollen Rumpf und die Kommentare liefert backlogGet.

backlogWrite

Schreibt ins Backlog-Cockpit. opsJson ist ein Objekt {"ops":[...]} oder direkt ein Array. Jede Operation traegt ein Feld op: create (title Pflicht; body, type, priority, epic, assignee, labels[], wikiSlug optional; Key wird vergeben), update (key Pflicht, dieselben Felder; Leerstring loescht ein Feld, Weglassen laesst es stehen), move (key + to = Zielstatus, note optional) und comment (key + body). Operationen laufen einzeln: eine fehlerhafte stoppt die uebrigen nicht. Jede Aenderung erzeugt ein Event mit source=AGENT und dem eigenen Client-Namen als actor.

deleteBrandingProfile

Loescht ein eigenes Branding-Profil. Built-ins sind nicht loeschbar. Veroeffentlichte Diagramme bleiben unveraendert; nur ein neuer Publish mit meta.profile=<geloeschter Name> scheitert.

deletePage

Löscht eine veröffentlichte Seite aus der Datenbank. Die Seite ist danach nicht mehr erreichbar.

diffDiagram

Strukturelles Delta zwischen zwei publizierten Versionen eines Diagramm-Bundles: added, removed, changed (Feld -> alt/neu in details) und rerouted (nur anders geroutet). Verglichen wird ein layoutfreies Modell: ein verschobener Knoten oder 1px versetzte Kanten erzeugen KEINEN Eintrag. Antwort: receipt (maschinenlesbare Quittung mit comparatorVersion, Hashes und Aenderungszeilen, genug fuer einen Aenderungstext ohne die Bilder), deltaUrl (Before|Delta|After unter /published/{slug}/delta) und summary. Fehlt einer Altversion die diagram.json, wird sie aus dem diagram.svg rekonstruiert (CANONICAL_FROM_SVG, Zonen-style nur genaehert). Fehler: DIAGRAM_DELTA_UNKNOWN_VERSION, DIAGRAM_DELTA_NOT_A_DIAGRAM. otherSlug vergleicht slug@fromVersion mit otherSlug@toVersion (Entwurf A gegen B; fehlende Versionen sind die aktuellen, receipt.toSlug nennt die Gegenseite). rules[] und lenses[] sind nicht Teil des Modells: ihren Stand melden validateDiagram und publishDiagram je Entwurf. Seitentext vergleicht listVersions(slug, versionA, versionB).

diffVersions

DEPRECATED -> listVersions. Dort versionA und versionB; funktioniert bis zur Messung unveraendert.

exportFigurePng

Liefert die Download-URL fuer die PNG-Fassung (transparent oder mit Papier-Hintergrund) einer bereits publizierten analog-v1-Figur (sketch-to-figure, siehe docs/agent-workflows/sketch-to-figure.md). Rastert nicht selbst -- die Rasterung passiert lazy beim ersten Abruf der URL. available=false heisst: unter diesem Slug wurde keine Figur mit dem az-svg-Konvent gefunden (kein figure.svg im Bundle).

extractTemplate

DEPRECATED -> publishArtifact. Template-Welt entfaellt; funktioniert bis zur Messung unveraendert.

fullTextSearch

Volltextsuche ueber Titel, Slug, Context und Seitentext (ohne HTML-Markup), nach Relevanz sortiert, hoechstens 100 Treffer. Versteht deutsche Wortformen (Diagramm findet Diagramme). Syntax: "genaue phrase", a or b, -ausschluss. Slug und Titel matchen zusaetzlich als Teilstring. matchedIn nennt die Trefferstellen (slug, title, context, body). Nuetzlich um 'alle Seiten die Keycloak erwaehnen' zu finden. Liefert Summary ohne Context-JSON.

getArtifactSource

R27/FR-3: liest zurueck, was tatsaechlich veroeffentlicht wurde — Content-Readback fuer raw_html-Seiten und Artefakt-Bundles. Bei einer Template-Seite liefert getPageContext (DEPRECATED, funktioniert) das Context-JSON, getArtifactSource den gerenderten Quelltext. Ohne path: das gespeicherte index.html (bzw. rawHtml) — bei Asset-Seiten aus R31 stattdessen die Datei selbst (asset.svg o.ae.), weil sie dort der Inhalt ist; der generierte Steckbrief bleibt ueber path='index.html' erreichbar. Mit path: eine benannte Begleitdatei des Bundles (z.B. 'app.js', 'style.css') als Text. Binaerdateien (Bilder, Fonts) werden abgelehnt — dies ist ein Quelltext-Reader, kein Datei-Download. maxBytes (Default 100000, Max 2000000) kuerzt grosse Dateien mit einem Hinweis am Ende statt den Kontext zu sprengen — analog web_fetch. Unbekannter Slug oder Pfad liefert einen strukturierten Fehler (PAGE_NOT_FOUND bzw. ASSET_NOT_FOUND).

getCapabilities

Selbstbeschreibung des Publishers als JSON und ERSTER CALL jedes Agenten, der etwas publizieren will: Groessenlimits, Endungen, Encodings, Slug-Regeln, gepinnte Bibliotheken ('libs': je EINE Zeile mit der neuesten Version, die richtige fuer ein neues Artefakt) und unter 'styling' das Klassen- und Modul-Vokabular von mzone-ui als Namensliste; wer daneben greift, bekommt UNKNOWN_STYLE_CLASS. styles='mz-card, mz-grid' liefert die vollen Katalog-Eintraege (ersetzt lookupStyles). include='minimal' haelt nur die harten Regeln. diagramType='flowchart' haengt Budget und Regeln dieses Typs an die Landkarte; den Typ allein samt Schema liefert topic='flowchart'. topic liefert Ausschnitte statt der Landkarte (ersetzt getCapabilityFor und listCapabilities): topic='list' nennt die Themen, sonst ein Thema, ein Diagramm-Typ oder ein Tool-Name (dessen Signatur), z.B. 'libs, icons, analog, publish'.

getCapabilityFor

DEPRECATED -> getCapabilities. Dort topic='<thema>'; funktioniert bis zur Messung unveraendert.

getDesignMdFor

DEPRECATED -> searchBranding. Ein exakter Codename trifft dort immer; funktioniert unveraendert.

getDiagramChatView

Nur fuer den Chat-Viewer (MCP Apps, MZP-126) -- ein Agent braucht dieses Tool nicht. Liefert das fertige index.html eines publizierten Diagramms (slug) oder einer Preview (previewToken aus validateDiagram). Genau einen der beiden setzen.

getPageContext

DEPRECATED -> getArtifactSource (liefert gerenderten Quelltext, nicht den Context-JSON). Dieses Tool liefert den Context-JSON unveraendert.

getPageHistory

DEPRECATED -> listVersions (nur Staende ueber publishArtifact). Audit-Zeilen je Slug nur hier und unter /admin/audit.

getPageStats

Gibt aggregierte Statistiken zurück: Anzahl Templates, veröffentlichte Seiten, Kategorien, Seiten der letzten 7 Tage

Keine Parameter.

getRatchetCityKit

Rezept fuer die Ratschen-Stadt in einem beliebigen Maven-Repo: jede Java-Datei als Haus (Grundflaeche und Hoehe nach Zeilen, Farbe nach JaCoCo-Abdeckung) in einer eigenstaendigen HTML-Datei, optional als isometrisches SVG samt Bildblock in der README. Das Tool fuehrt nichts aus: Du fuehrst die Schritte lokal in der Shell des Repos aus (steps, bash oder powershell), laedst das Kit mit Pruefsummen (files, vendor) und rufst build.py mit den Parametern auf. Es wird nichts hochgeladen. Farben und Titel setzt du ueber theme.json (theme.keys) und --title; ohne Angabe gilt der Look des mzone-publisher. Die README wird nur mit --readme angefasst.

Keine Parameter.

getTemplate

DEPRECATED -> publishArtifact. Template-Welt entfaellt; funktioniert bis zur Messung unveraendert.

listAssetUsage

R32: die Herkunfts-Achse in Gegenrichtung — welche Seiten haben deklariert, dass sie dieses Asset verwenden? Eine Seite deklariert das ueber usedAssets im metadataJson bei publishArtifact/publishAsset/publishPage. Nuetzlich vor dem Ueberschreiben eines aktiven (trust:active) Assets: die ASSET_UPDATED-Notice, die publishAsset bei einem Republish zurueckgibt, listet dieselben Seiten. Ohne deklarierte Nutzung leer — das Asset koennte trotzdem kopiert worden sein, nur eben nicht nachverfolgbar.

listCapabilities

DEPRECATED -> getCapabilities. Dort topic='list'; funktioniert bis zur Messung unveraendert.

Keine Parameter.

listPublishedPages

Listet veroeffentlichte Seiten als BLOCK mit schlankem Summary (Slug, Titel, Template-Name, Aenderungsdatum, URL, status, supersededBy, kind, mediaType). KEIN Context-JSON. H3: der Aufruf liefert standardmaessig 50 Seiten, nicht alle — die Antwort traegt total und nextCursor; nextCursor an den naechsten Aufruf weiterreichen blaettert weiter, null bedeutet letzter Block. limit maximal 200, darueber wird geklemmt. Context-JSON einer Template-Seite: getPageContext(slug) (DEPRECATED, funktioniert); gerenderter Quelltext: getArtifactSource(slug). Fuer Suche: fullTextSearch(query). Optionaler status-Filter (draft|current|superseded|archived, R28/FR-4): status='current' liefert nur gueltige Seiten, ohne die ueberholten Duplikate. Optionaler kind-Filter (page|asset, R31): kind='asset' ist der Katalog der Asset-Bibliothek. K07: fields='slug,title,status' liefert nur diese Felder (Kompaktmodus, Token-sparend).

listTemplates

DEPRECATED -> publishArtifact. Template-Welt entfaellt; funktioniert bis zur Messung unveraendert.

Keine Parameter.

listVersions

Snapshot-Historie eines Slugs: jede Version mit Zeitstempel, Groesse, Dateianzahl und publizierendem Agenten, neueste zuerst, der aktuelle Stand mit current=true. Mit versionA und versionB (Nummern aus dieser Liste) stattdessen Dateiliste plus Unified-Diff zwischen den beiden Staenden: unveraenderte Dateien fehlen, Textdateien tragen einen Diff mit 3 Zeilen Kontext, Binaerdateien und Textdateien ueber 20000 Zeilen einen SHA-256-Vergleich. Beim Ueberschreiben via publishArtifact wird der vorherige Stand automatisch gesichert.

lookupStyles

DEPRECATED -> getCapabilities. Dort styles='<namen>'; funktioniert bis zur Messung unveraendert.

publishArtifact

PRIMAERER WEG zum Publizieren interaktiver HTML-Artefakte (Reports, 3D-Visualisierungen, Single-File-Apps): ein Bundle aus index.html plus beliebigen Begleitdateien, alle relativ zur index.html (kein CDN noetig), erreichbar unter https://publisher.maierzone.de/published/{slug}/ . Das Bundle kommt aus GENAU EINER Quelle: html (eine Datei), files (Array), stagingToken (aus validateArtifact, ohne erneute Uebertragung) oder filesJson (Alt-Weg). Was der Server schon haelt, per fromSlug/fromPath referenzieren statt neu senden. Existiert der Slug, scheitert der Call ohne overwrite=true; der alte Stand bleibt als Version (listVersions/rollbackArtifact). Rueckgabe: url, version, notices (code/severity/subject), reachability (allOk=false: gespeichert, aber falsch ausgeliefert) und der Browser-Blick (CONSOLE_ERROR, PAGE_EXCEPTION, RESOURCE_FAILED). Limit 10 MB dekomprimiert. Ein analog-Blatt ist ein Artefakt (dieses Tool), kein Diagramm; eine Zahl, die beim Oeffnen aktuell sein soll, ist liveData, nicht eingeschrieben. Weitere Weichen (compact, grosse Dateien, patch): getCapabilities(topic='publish').

publishAsset

Legt EINE Datei als eigene, auffindbare Seite ab (Asset-Bibliothek, Slug 'asset-{name}'), z.B. ein SVG, ein Diagramm, einen Datensatz. Unter /published/{slug}/ entsteht ein Steckbrief, die Datei liegt unter asset.{endung}. title/description/tags im metadataJson sind der Text, ueber den fullTextSearch das Asset findet; getArtifactSource liefert den Quelltext. Vertrauen: inerte Formate (svg, png, jpg, json, md, csv, txt ...) duerfen blind kopiert werden, html/js/css sind trust:active und erst nach Lesen verwendbar; ein SVG mit aktiven Inhalten wird abgelehnt (ACTIVE_SVG_CONTENT). Details: getCapabilities(topic='publish').

publishDiagram

Rendert Diagramm-JSON serverseitig im maierzone-Skin und publiziert index.html + diagram.svg unter /published/{slug}/ — mit Versionierung, Overwrite-Schutz und Audit wie publishArtifact (ADR-011, Delegation an dieselbe Artefakt-Pipeline). ZWEI WEGE, GENAU EINEN setzen: (1) diagramJson — parst und validiert wie validateDiagram (dessen Hinweise wie RULE_VIOLATED stehen im Ergebnis), ein ungueltiges Diagramm scheitert mit DIAGRAM_INVALID statt zu publizieren. (2) stagingToken — der previewToken aus validateDiagram; das dort bereits gerenderte Bundle wird publiziert, ohne erneut zu rendern oder zu uebertragen. Beides fehlend liefert MISSING_INPUT. Nach dem Publish zaehlt ein echter Browser nach (visualProof): sichtbare Formen, Elemente ohne Ausdehnung und Elemente ausserhalb der Zeichenflaeche. Weicht das von der Renderer-Bilanz ab, kommt RENDER_MISMATCH als WARNING — der Publish bleibt davon unberuehrt.

publishPage

DEPRECATED -> publishArtifact. Template-Welt entfaellt; funktioniert bis zur Messung unveraendert (ADR-Pfad offen).

publishQuiz

Baut aus Fragen ein Multiple-Choice-Quiz und publiziert es als selbstlaufende Seite quiz-<titel> (Punktestand und Wiederholung nur im Browser des Spielers, kein Backend). Du schreibst nur die Fragen; Validierung, Seitenbau, Publish und Rueckpruefung uebernimmt der Server. Regeln: genau 4 Optionen, richtig = Index 0..3, keine doppelten oder leeren Optionen, keine Sammeloptionen ('alle der oben', 'beides'), erklaerung Pflicht, niveau leicht|mittel|schwer, richtige Position gleichverteilt. Bei Verstoss kommt QUIZ_INVALID mit ALLEN Fehlern; korrigieren und erneut senden. Ein bestehender Slug wird ueberschrieben (alter Stand bleibt als Version, listVersions/rollbackArtifact). Empfohlener Ablauf: Prompt 'mzp-quiz'.

publishRawPage

DEPRECATED -> publishArtifact. Dort html='<dokument>' mit slug; ein vorhandener Slug braucht overwrite=true. Funktioniert bis zur Messung unveraendert.

publishRawPageCompressed

DEPRECATED -> publishArtifact. Dort files mit contentBase64 und encoding; ein vorhandener Slug braucht overwrite=true. Funktioniert bis zur Messung.

queryDiagram

Befragt den Graphen eines publizierten Diagramm-Bundles, ohne dass die diagram.json in den Kontext muss. direction=in: was fuehrt zu nodeId (stromauf), out: was haengt daran (stromab) — transitiv, mit depth begrenzbar (1 = direkte Nachbarn). direction=paths: alle einfachen Pfade von nodeId nach to, kuerzester zuerst, hoechstens 10 (truncated sagt, ob es mehr gab); kein Pfad ist eine leere Liste, kein Fehler. Kanten gelten gerichtet wie gespeichert. Die Antwort traegt nur Ids, Labels und Kanten-Keys, keine Geometrie. Versionsvergleiche macht diffDiagram.

renderPreview

DEPRECATED -> publishArtifact. Template-Welt entfaellt; funktioniert bis zur Messung unveraendert.

revokePreview

R13: einen Review-Link vor seinem Ablauf ungueltig machen. Wirkt sofort — die URL antwortet danach mit 404, unabhaengig davon, wer sie schon hat. Gilt nur fuer langlebige Links aus validateArtifact(reviewTtlSeconds); kurze Standard-Previews laufen ohnehin nach 15 Minuten aus. Unbekannter, abgelaufener oder bereits widerrufener Token liefert revoked=false statt eines Fehlers: das Ergebnis ist dasselbe, der Link funktioniert nicht mehr.

rollbackArtifact

Stellt eine fruehere Version wieder her — inklusive aller Assets, nicht nur des HTML. Der aktuelle Stand wird vorher selbst gesichert, ein Rollback ist also ebenfalls reversibel. Verfuegbare Versionen: listVersions(slug).

saveBrandingProfile

Legt ein eigenes Branding-Profil an oder aendert es (Upsert); danach rendert meta.profile=<codename> in validateDiagram/publishDiagram damit. Pflicht: codename, mode (light|dark, eine Palette je Profil), vibe, colors.surface/text/accent; optional colors.primary/secondary (werden series1/2), voice, theme (Ueberschreibung einzelner Theme-Felder wie muted, link, rule), typography, layoutPrinciples. Der Server leitet die uebrigen Theme-Felder ab und prueft den Kontrast (Text unter 4.5:1 ist ein Fehler, Akzent unter 3:1 eine Warnung); das abgeleitete Theme steht im Ergebnis. Built-ins (nightline, ledger, monoblock, arcade) sind nicht ueberschreibbar. Beispiel: {"codename":"acme","mode":"light","vibe":"Sachlich, blau","colors":{"surface":"#FFFFFF","text":"#1B1F23","accent":"#0B6BCB"}}

searchBranding

Sucht unter den Branding-Profilen fuer Diagramme/Artefakte (mitgelieferte nightline, ledger, monoblock, arcade und eigene aus saveBrandingProfile; `source` sagt welche) — exakter Codename trifft immer, Freitext wird gegen die vibe-Beschreibung gesucht (z.B. 'verspielt' -> arcade). Liefert bei Treffer das volle Basis-Profil. Diese Werte sind eine BASIS, kein festes Regelwerk: einzelne Tokens (Farbe, Dichte, Typo) duerfen vor Gebrauch frei angepasst werden.

searchPages

DEPRECATED -> fullTextSearch (auch Seitentext, max. 100 Treffer). Slug-Kataloge: listPublishedPages(kind='asset'|'page'), Praefix selbst filtern.

setPageLifecycle

R28/FR-4: markiert eine Seite als draft|current|superseded|archived und/oder setzt ihren Nachfolger. Wird supersededBy gesetzt, ist der Status implizit superseded — status muss dann nicht separat mitgegeben werden. Der Server prueft, dass der Nachfolger existiert (Fehler SUCCESSOR_NOT_FOUND) und dass keine Zyklen entstehen (Fehler LIFECYCLE_CYCLE). Alte Seiten bleiben erreichbar (kein Loeschen) — sie bekommen beim Ausliefern einen Hinweisbanner auf den Nachfolger. listPublishedPages(status:'current') filtert danach die ueberholten Duplikate raus.

validateArtifact

Prueft ein Bundle OHNE es zu speichern (Groessen, Dateitypen, index.html, kaputtes HTML, CDN-Referenzen, tote relative Links) und legt eine Preview an: previewUrl (Default 15 min) plus previewToken, der als stagingToken an publishArtifact geht, ohne das Bundle erneut zu senden. Gleiche Quellen wie publishArtifact (html, files, filesJson, fromSlug). Die Preview wird in einem echten Browser geladen (CONSOLE_ERROR, PAGE_EXCEPTION, RESOURCE_FAILED, 2-4 s); ein Befund der Stufe ERROR macht ok=false. Review-Links fuer Externe (reviewTtlSeconds, max 7 Tage) und Widerruf: getCapabilities(topic='publish').

validateDiagram

Prueft Diagramm-JSON (oder mermaid/ascii/drawio) OHNE zu speichern: Schema, 4px-Grid, Komplexitaets-Budgets, Connector-Geometrie, Taste-Warnungen. Bei Erfolg kommt eine TTL-Preview (index.html + diagram.svg) mit previewToken, den publishDiagram als stagingToken annimmt, ohne neu zu rendern. renderSummary zaehlt die tatsaechlich gezeichneten Knoten, Kanten, Zonen und typ-spezifischen Elemente; kommt nichts heraus, schlaegt die Pruefung fehl (EMPTY_RENDER, TYPE_BLOCK_EMPTY). Connectors muessen NICHT von Hand geroutet werden: Andock-Seite, Verteilung und Ausweichen rechnet der Server; waypoints sind Steuerpunkte, edges[].props.fromSide/toSide erzwingt eine Seite. Typen, Feldnamen und Budgets: getCapabilities(topic='<typ>') bzw. getCapabilities(diagramType='<typ>').