94 lines
7.9 KiB
Markdown
94 lines
7.9 KiB
Markdown
---
|
|
name: pdfcraft-mcp
|
|
description: PDFs über den PdfCraft-MCP-Server öffnen, auslesen, schwärzen, bereinigen, zusammenführen, aufteilen, mit Kopf-/Fußzeile, Seitenzahlen, Wasserzeichen und Lesezeichen versehen und nach Word exportieren. Verwenden, wenn PdfCraft-Werkzeuge verbunden sind oder der Nutzer PdfCraft nennt; typisch für Schwärzen vor der Weitergabe, Dokumentationspakete (Betriebsanleitung, Datenblätter, Konformitätserklärung), Angebote und Zeichnungen auslesen.
|
|
---
|
|
|
|
# PDFs mit PdfCraft (MCP)
|
|
|
|
PdfCraft ist ein Open-Source-PDF-Programm (Rust), das Acrobat-Pro-Parität anstrebt. Getestet mit Version 0.9.0.
|
|
|
|
## Voraussetzung
|
|
|
|
Die Werkzeuge `doc_open`, `text_extract`, `tool_search`, `tool_call` … müssen verbunden sein. Ihr Präfix hängt vom Client und vom Namen der Erweiterung bzw. des Servers ab (z. B. `mcp__…__PdfCraft_for_Claude__doc_open`). 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.
|
|
|
|
Der Server läuft im **Kompaktmodus** (`--compact`): Er zeigt 17 Kernwerkzeuge. Die übrigen gut 150 erreicht man über `tool_search` und `tool_call`. Ohne Kompaktmodus wären es 171 Werkzeuge mit rund 45.000 Tokens Beschreibung.
|
|
|
|
Dateizugriff: Lesen nur im Lese-Ordner, Schreiben nur im Schreib-Ordner. Andere Pfade werden mit `automation path rejected: outside the read root …` bzw. `… write root …` abgelehnt. Das ist ein normaler Fehler: dem Nutzer den erlaubten Ordner nennen. Der Schreib-Ordner muss **im** Lese-Ordner liegen (z. B. Lese = Dokumente, Schreib = Dokumente\Claude), sonst lassen sich eigene Ergebnisse nicht wieder öffnen.
|
|
|
|
## Werkzeuge
|
|
|
|
| Direkt | Zweck |
|
|
|---|---|
|
|
| `doc_open` / `doc_close` / `doc_save` | öffnen (liefert `doc`-Nummer), schließen, speichern (`path` = neue Datei) |
|
|
| `doc_info` / `doc_inspect` | Seiten, Metadaten, Zustand |
|
|
| `text_extract` / `text_find` | Text je Seite; Fundstellen mit Rechtecken |
|
|
| `page_render` / `render_preview` | Seite als PNG ansehen |
|
|
| `doc_combine` / `doc_split` | zusammenführen / aufteilen |
|
|
| `edit_undo` | rückgängig |
|
|
| `command_list` / `command_run` / `command_batch` | Befehlskatalog |
|
|
| `tool_search` / `tool_call` | alle weiteren Werkzeuge finden / ausführen |
|
|
|
|
Wichtige Werkzeuge über `tool_call`: `redact_mark`, `redact_apply`, `doc_audit_redactions`, `doc_hidden_info`, `doc_remove_hidden`, `doc_header_footer`, `doc_watermark`, `page_add_text`, `bookmark_list`/`bookmark_add`/`bookmark_rename`, `page_delete`/`page_move`/`page_rotate`/`page_extract`/`page_insert_file`, `doc_export_office`, `doc_export_text`, `form_fields`/`form_fill`, `comment_list`, `doc_compare`, `doc_protect`, `ocr_status`/`ocr_recognize`, `pdfa_verify`.
|
|
|
|
## Arbeitsweise
|
|
|
|
1. **Parameter nie raten:** Vor dem ersten Aufruf eines Werkzeugs `tool_search {name: "<werkzeug>"}`. Die Namen sind uneinheitlich, z. B. `doc_combine {out}`, `doc_split {out_dir}`, `doc_set_info {key, value}`. Unbekannte Parameter werden mit `-32602` abgelehnt und der Fehler nennt die erlaubten. Dann korrigieren und erneut aufrufen.
|
|
2. **Seiten zählen ab 1.** Rechtecke sind PDF-Punkte, Ursprung oben links (1 mm = 2,835 pt).
|
|
3. Änderungen bleiben im Speicher, bis `doc_save` aufgerufen wird. Bis dahin lassen sie sich mit `edit_undo` zurücknehmen.
|
|
4. **Speichern immer unter neuem Namen** in den Schreib-Ordner (`doc_save {doc, path}`). `doc_save` ohne `path` überschreibt die geöffnete Datei.
|
|
5. **Prüfen:** `render_preview` ansehen, `text_extract` gegenlesen, gespeicherte Datei neu öffnen.
|
|
|
|
## Fallen (im Test bestätigt)
|
|
|
|
- **Schwärzen erfasst nur, was markiert ist.** `redact_mark {find: "EUR"}` schwärzt nur „EUR“, der Betrag davor bleibt stehen. Ganze Werte markieren:
|
|
- per `words` (Liste exakter Werte) oder
|
|
- per Rechteck: mit `text_find` das Label suchen (z. B. „Preis:“), dann `redact_mark {page, rect: [x1+2, y0-1, <rechter Rand>, y1+1]}`.
|
|
- **`overlay`-Text ist echter Text.** Er erscheint danach in `text_extract` und in der Datei. Nur neutrale Wörter verwenden („geschwärzt“), nie den Originalwert.
|
|
- **`redact_mark` allein entfernt nichts.** Erst `redact_apply` löscht endgültig. Danach `doc_audit_redactions`: Es findet Scheinschwärzungen (schwarze Kästen über weiterhin lesbarem Text) und nicht angewendete Markierungen.
|
|
- **Metadaten:** `doc_hidden_info` zeigt Autor, Programm, Kommentare, Anhänge, versteckte Ebenen; `doc_remove_hidden` entfernt sie. Vor jeder Weitergabe ausführen.
|
|
- **Muster** für `redact_mark {pattern}`: `email`, `phone`, `date`, `credit-card`, `ssn`. Es gibt kein Muster für Geldbeträge und keins für Namen; diese per `words` oder Rechteck schwärzen.
|
|
- **`doc_combine {paths, out, open: true}`** schreibt die Datei sofort. Das geöffnete Ergebnis heißt „Combined“ und hat keinen Pfad: Spätere Änderungen mit `doc_save {path}` speichern. Lesezeichen heißen danach wie die Quelldateien; mit `bookmark_rename` umbenennen.
|
|
- **Kopf-/Fußzeile:** `doc_header_footer {footer_right: "Seite <<1>> von <<n>>"}` funktioniert. Datums-Platzhalter gibt es nur amerikanisch (`<<m/d/yyyy>>`, `<<d/m/yyyy>>`, `<<yyyy-mm-dd>>`), `<<dd.mm.yyyy>>` bleibt als Text stehen. Das Datum ausgeschrieben einsetzen (`Stand 19.10.2026`).
|
|
- `page_add_text`/Kopfzeilen: Schriften nur helvetica, times, courier; Umlaute, ß und € gehen.
|
|
- **OCR:** vorher `ocr_status`. Ohne mitgelieferte Sprachmodelle ist `available: false`; dann dem Nutzer sagen, dass gescannte PDFs nicht durchsuchbar gemacht werden können.
|
|
|
|
## Rezepte
|
|
|
|
1. **Schwärzen vor der Weitergabe** (z. B. Kunden-PDF für eine Vorlage oder Cloud-KI):
|
|
1. `doc_open`.
|
|
2. Markieren:
|
|
- `redact_mark {pattern: "email"}` und `{pattern: "phone"}`;
|
|
- `{words: [Namen, Firma, Adresse]}` mit den Werten vom Nutzer;
|
|
- Beträge per Rechteck.
|
|
3. `redact_apply`, dann `doc_audit_redactions` (Ergebnis muss `count: 0` sein), dann `doc_remove_hidden`.
|
|
4. `text_extract` auf Reste prüfen und `render_preview` ansehen.
|
|
5. Mit `doc_save {path: "<name>_geschwaerzt.pdf"}` speichern.
|
|
2. **Dokumentationspaket:** `doc_combine {paths: [Deckblatt, Konformitätserklärung, Betriebsanleitung, Datenblätter, Schaltplan], out, open: true}` → Lesezeichen umbenennen → `doc_header_footer` (Projekt, „Seite <<1>> von <<n>>“) → ggf. `doc_watermark {text: "ENTWURF", opacity: 0.15}` → `doc_save {path}`.
|
|
3. **Auslesen:** `text_extract {doc, pages}` bzw. `text_find`; Tabellen/Formulare über `form_fields`. Ergebnis als Text/Tabelle zurückgeben, Original nicht verändern.
|
|
4. **Nach Word:** `doc_export_office {doc, path: "….docx"}`, danach mit WordCraft weiterbearbeiten.
|
|
|
|
## Abschlussprüfung
|
|
|
|
- Alle geänderten Seiten mit `render_preview` angesehen.
|
|
- Bei Schwärzungen: `doc_audit_redactions` hat `count: 0`, `text_extract` zeigt keine geschwärzten Werte, `doc_hidden_info` ist leer.
|
|
- Gespeicherte Datei neu geöffnet, Seitenzahl plausibel, Pfad dem Nutzer genannt.
|
|
|
|
## Datenschutz
|
|
|
|
Ampel:
|
|
- 🟢 Allgemeine und technische Inhalte ohne Kundenbezug.
|
|
- 🟡 Projekt- und Geschäftsinfos, Preise: nur nach Abwägung oder anonymisiert.
|
|
- 🔴 Personenbezogene Daten und NDA-Inhalte gehören nicht in die Cloud-KI.
|
|
|
|
**Blind schwärzen** bei 🔴-Dokumenten: Das Original nie mit `text_extract`, `page_render`, `render_preview` oder `doc_audit_redactions` lesen. Diese Werkzeuge schicken den Inhalt ans Modell. Stattdessen:
|
|
1. Nur mit Mustern und vom Nutzer genannten Werten markieren (`redact_mark` meldet nur Anzahlen).
|
|
2. Erst nach `redact_apply` das Ergebnis ansehen und prüfen.
|
|
|
|
Dem Nutzer sagen, welche Kategorien geschwärzt wurden, und ihn das Ergebnis selbst gegenlesen lassen.
|
|
|
|
## Grenzen
|
|
|
|
- Digitale Signaturen: Nach Schwärzen, Zusammenführen oder Seitenänderungen ist eine bestehende Signatur ungültig. Den Nutzer vorher darauf hinweisen.
|
|
- Komplexe Layouts exportieren nur näherungsweise nach Word (`doc_export_office`).
|
|
- Formulare und JavaScript nur bearbeiten, wenn der Nutzer das ausdrücklich will.
|