claude-skills/skills/wordcraft-mcp/SKILL.md

name, description

name	description
wordcraft-mcp	Word-Dokumente (.docx, .odt, .md, PDF) mit dem WordCraft-MCP-Server erstellen, bearbeiten und prüfen (inkl. Nachverfolgung). Verwenden, wenn WordCraft-Werkzeuge verbunden sind oder der Nutzer WordCraft nennt; typisch für Angebote, Briefe, Betriebsanleitungen, Arbeitsanweisungen, 8D-Reports, Vorlagen. Nicht für eingebaute docx-Hilfen ohne WordCraft-Server.

Dokumente mit WordCraft (MCP)

WordCraft ist ein Open-Source-Textverarbeitungsprogramm (Rust), das Word-Parität anstrebt. Alles ist ein Befehl mit stabiler ID; Ribbon, CLI und MCP rufen dieselben Befehle auf.

Voraussetzung

Die Werkzeuge list_commands, execute, render_page … müssen verbunden sein. Ihr Präfix hängt vom Client und vom Namen der Erweiterung bzw. des Servers ab (z. B. mcp__…__WordCraft_for_Claude__list_commands). Sind sie zurückgestellt, nach dem Werkzeugnamen ohne Präfix suchen und alle benötigten auf einmal laden. Fehlen sie, dem Nutzer sagen, dass der Server nicht verbunden ist (Einrichtung siehe README), statt auf ein anderes Programm auszuweichen.

Freigaben

Schutz durch Lese- und Schreib-Root (nicht die Freigabe-Dialoge). Lesen weit, Schreiben eng. Zusammenhängende Schritte immer als batch. Genau Dateipfade vom Nutzer erfragen statt zu raten.

Tools

Tool	Zweck
list_commands	alle Befehle, mit query filtern
execute	einen Befehl ausführen: {command, params}
batch	mehrere Befehle in Reihenfolge (stoppt beim ersten Fehler)
new_document	blank, sample, letter, resume, report
open_document / save_document	docx, doc (nur öffnen), odt, rtf, html, md, tex, txt, json, xml (Flat OPC; CLI --format wordml2003 für Word 2003 XML); speichern auch pdf, png
type_text	an der Schreibmarke tippen (ersetzt Markierung)
select_text	n-tes Vorkommen eines Textes markieren
get_text / inspect_document	Dokument zurücklesen (Struktur als JSON, inkl. Kopf-/Fußzeilen unter parts)
render_page	Seite als PNG
parity	Funktionsabdeckung gegenüber Word
screenshot, click, key, ui_inspect	nur mit verbundener Desktop-App

Arbeitsweise

1. Befehls-IDs nie raten. Vor jedem unbekannten Befehl list_commands mit query aufrufen (z. B. table., insert., layout., styles., review, caret., select.).
2. Alles im batch. Auch Markieren: select.text {text, occurrence?}, select.range {anchor: Pos, focus: Pos}, select.collapse. text.insert ersetzt eine bestehende Markierung. Damit lassen sich ganze Dokumente in wenigen Aufrufen umbauen.
3. Formatvorlagen statt Direktformatierung. styles.modify an Normal/Heading1/Heading2/Title; Absätze nur per para.set {"props":{"style":"Heading1"}} zuweisen.
4. Prüfen, bevor gespeichert wird. inspect_document, render_page.
5. Speichern mit save_document in den Schreibordner; PDF per Endung .pdf.
6. Rundreise prüfen: gespeicherte Datei neu öffnen und erneut prüfen.

Dateien finden und Zugriff

Es gibt keinen Befehl zum Auflisten von Ordnern. open_document auf einen Pfad:

• os error 5 (Zugriff verweigert) → Pfad ist ein existierender Ordner
• os error 2 (nicht gefunden) → existiert nicht

Liegt eine Datei außerhalb des Lese-Ordners, wird sie abgelehnt. Dann: (a) Nutzer bitten, den Lese-Ordner in den Einstellungen weiter zu fassen, oder (b) – wenn der Client Dateizugriff mit Nutzerfreigabe hat – die Datei mit Freigabe in den Arbeitsordner kopieren und nur mit der Kopie arbeiten. Original nie überschreiben.

Neues Dokument – Grundeinrichtung (DE)

new_document blank übernimmt das Papier der Systemregion (CLI 0.11.0: A4, in Letter-Regionen US-Letter; WORDCRAFT_REGION setzt die Region fest). Auf diesem Rechner war ein leeres Dokument A4 (11906×16838 Twip), die Ränder 1 Zoll. Sprache und Ränder deshalb weiter explizit setzen:

[{"command":"layout.size","params":{"name":"A4"}},
 {"command":"layout.margins","params":{"top":70.87,"bottom":56.69,"left":70.87,"right":56.69}},
 {"command":"review.language","params":{"lang":"de-DE","default":true}},
 {"command":"styles.modify","params":{"style":"Normal","chr":{"font":"Arial","size":10.5,"lang":"de-DE"}}}]

Ohne de-DE zeigt render_page deutsche Wörter mit roten Wellenlinien.

Text aufbauen: para.set {style} → text.insert → text.newParagraph, Stil für jeden Absatz explizit setzen.

Fallen (im Test bestätigt)

• format.set ohne Markierung wirkt nicht auf den gerade eingefügten Text, sondern auf den folgenden Absatz. Immer erst markieren (select.text / select.range), dann formatieren.
• Nummerierte Listen: para.numbering {"kind":"numbered"} (auch numberedParen, upperLetter, lowerLetter, lowerRoman, outline). para.bullets {"kind":"decimal"} nimmt „decimal“ still als Aufzählungszeichen. Ende: para.numbering {"off":true}. Aufzählung: para.bullets {"kind":"bullet"} … para.bullets {"off":true}.
• table.insertRowBelow übernimmt Ausrichtung und Fettdruck der Nachbarzeile nicht → danach para.set {align} und format.set setzen.
• Absätze mit gemischtem Format (z. B. fettes Label + Tab + Wert): nicht den ganzen Absatz ersetzen (sonst übernimmt alles das Format des ersten Laufs), sondern nur den Wertteil per select.text.
• inspect_document: len und alle off sind UTF-8-Bytes (ä/ö/ü/ß = 2). Für Textstellen mit Umlauten lieber select.text als selbst berechnete Offsets.
• Absätze löschen: von unten nach oben arbeiten; select.range vom Ende (off = len) des letzten verbleibenden Absatzes bis zum Ende des letzten zu löschenden Absatzes, dann text.delete. Indizes danach neu berechnen.
• Hinweiskasten: para.set {"props":{"shading":[r,g,b],"borders":{"top":{…},"bottom":{…},"left":{…},"right":{…}}}}; im nächsten Absatz zurücksetzen (shading weiß, borders style none).
• Abstand vor einem Absatz: para.set {"props":{"style":"Normal","spaceBefore":24}}.
• Gelbe Platzhalter-Markierung (format.set {"props":{"highlight":"yellow"}}) bleibt beim Überschreiben erhalten – Nutzer bei Vorlagen darauf hinweisen (Word: Strg+A → Texthervorhebung „Keine Farbe“).

Kopf- und Fußzeile, Seitenzahl

• Nach insert.header / insert.footer sofort insert.closeHeader, sonst landet folgender Text in der Kopf-/Fußzeile.
• insert.footer {"text": ...} setzt die Schreibmarke an den Anfang des Textes. preset: "blank" legt „[Type here]“ an. Deshalb ohne Parameter öffnen und dann tippen:

[{"command":"insert.footer"},
 {"command":"text.insert","params":{"text":"Seite "}},
 {"command":"insert.pageField"},
 {"command":"text.insert","params":{"text":" von "}},
 {"command":"insert.field","params":{"instr":"NUMPAGES","result":"1"}},
 {"command":"para.set","params":{"props":{"align":"center"}}},
 {"command":"insert.closeHeader"}]

• Kontrolle: inspect_document → parts[] mit kind: header/footer.

Tabellen

• insert.table {"rows":n,"cols":n,"style":"TableGrid"} liefert {"table":[index]} = Blockindex.
• Zellen nicht per Tab füllen, sondern anspringen: caret.set {"pos":{"path":[tabelle, zeile, spalte, 0],"off":0,"story":"body"}} dann text.insert.
• Kopfzeile: Caret in Zeile 0 → table.properties {"headerRow":true}, table.selectRow, table.shading {"color":"D9E2F3"}, format.set {"props":{"bold":true}}.
• table.columnWidth ändert nur die Spalte der Schreibmarke. Alle Spalten so setzen, dass die Summe = Satzspiegel (A4 mit 2,5/2 cm ≈ 467,7 pt).

Überarbeitung fremder Dokumente (Nachverfolgung)

1. Original nur öffnen, nie darauf speichern; erste Speicherung sofort mit neuem Namen in den Schreibordner.
2. file.setAuthor {"name":"…"} und review.trackChanges {"value": true} – immer mit value.
3. Ersetzen: select_text → type_text. Ergebnis ist Einfügung + Löschung.
4. select_text findet auch bereits nachverfolgt gelöschten Text. Nach einer Ersetzung nicht erneut nach dem alten Wortlaut suchen.
5. Begründungen als Kommentar: Text markieren, review.newComment {"text": ...}.
6. Prüfen: review.changes und review.comments – auch nach dem Neuöffnen.

Rezepte

Platzhalter-Konvention: {{Feldname}} (Jinja2-kompatibel).

1. Neues Dokument

A4, Ränder, de-DE, Formatvorlagen Title/Heading1/Heading2/Normal anpassen → Inhalt aufbauen → Kopfzeile → Fußzeile „Seite x von y“ → Tabelle mit Kopfzeile → nummerierte Liste (para.numbering) → ggf. Hinweiskasten → render_page → speichern.

2. Vorlage aus bestehendem Dokument

Kopie im Lese-Ordner öffnen → inspect_document → Löschungen von unten nach oben → Ersetzungen per select.range (Absatzindex) bzw. select.text (Teilstücke) → Platzhalter {{Feldname}} gelb markieren → get_text prüfen, dass keine Ursprungsdaten (Namen, Adressen, Preise) übrig sind → unter neuem Namen speichern.

3. Vorlage füllen

Vorlage öffnen → Felder per select.text "{{Feld}}" + text.insert im batch ersetzen → wiederholbare Listenpunkte ergänzen/löschen → Markierung entfernen → get_text auf {{ prüfen → rendern → unter neuem Namen speichern (.docx + .pdf).

Abschlussprüfung

• Alle Seiten mit render_page ansehen; Seitenzahl plausibel.
• Bei Vorlagen/gefüllten Dokumenten: get_text auf {{ bzw. Altdaten prüfen.
• Gespeicherte Datei neu öffnen und kurz gegenlesen.
• Pfad dem Nutzer nennen.

Datenschutz

• Grün: allgemeine/technische Inhalte ohne Kundenbezug.
• Gelb: Projekt-/Geschäftsinfos, Preise (oft vertraulich) nur nach Abwägung oder anonymisiert.
• Rot: personenbezogene Daten (Ansprechpartner, E-Mail, Telefon) und NDA-Inhalte nicht in die Cloud-KI.
• Vorlagen aus geschwärzten Kopien erstellen; im Freitext Platzhalter statt echter Namen verwenden.

Eigenschaften (Kurzreferenz)

Längen in Punkt, Farben als "#RRGGBB", [r,g,b] oder {"Rgb":[r,g,b]}; bei Tabellenbefehlen "RRGGBB" ohne #. Unbekannte Feldnamen werden still ignoriert.

• Zeichen (format.set {"props": …}): font, size, bold, italic, underline, color, highlight, vertAlign, lang, link
• Absatz (para.set {"props": …}): style, align, indentLeft, indentFirst, spaceBefore, spaceAfter, lineSpacing ({"rule":"multiple","value":1.15}), keepNext, keepLines, pageBreakBefore, outlineLevel, numbering, tabs, borders, shading

Renderer-Grenzen (an 0.8.0 gesehen)

An 0.11.0 nicht erneut geprüft:

• mehrzeilige Zellen in dunkel hinterlegten Tabellenköpfen zeigen nur die letzte Zeile
• Seitenzahlfelder in Fußzeilen importierter python-docx-Dokumente bleiben leer

Bei Auffälligkeiten erst das Original rendern und vergleichen.

Word-Kompatibilität

• Bei unbekannten Funktionen parity abfragen.
• Original nie überschreiben.
• Nutzer bitten, das Ergebnis in Word zu öffnen und gegen das Original zu prüfen (ggf. review.compare).

Grenzen

• Die Ordner-Flags gelten nur kopflos. mcp --connect HOST:PORT und --automation-read-root / --automation-write-root zusammen sind ein Fehler (CLI 0.11.0). Mit verbundener App entfällt die Ordnersperre.
• Befehle ohne Pfad wirken immer auf das zuletzt geöffnete Dokument. Vor dem Öffnen eines anderen Dokuments speichern.
• Passwortgeschützte Dateien: die CLI nimmt --password, --password-file oder WORDCRAFT_PASSWORD und schreibt das Passwort wieder mit. Ob open_document ein Passwort-Feld hat, ist nicht geprüft.
• Zotero (CLI, Zotero muss laufen): addEditCitation, addEditBibliography, addNote, refresh, removeCodes, setDocPrefs. Kein eigenes MCP-Werkzeug dafür geprüft.