--- name: gridcraft-mcp description: Excel-Arbeitsmappen (.xlsx, .csv) über den GridCraft-MCP-Server erstellen, öffnen, ändern, berechnen, formatieren und prüfen – Kalkulationen, Stücklisten, Listen, Diagramme, PDF-Export. --- # Tabellen mit GridCraft (MCP) GridCraft ist eine Open-Source-Tabellenkalkulation (Rust), die Excel-Parität anstrebt. Alles ist ein Befehl mit stabiler ID nach dem Excel-Ribbon (`home.bold`, `insert.chart`, `data.sort` …); Ribbon, CLI und MCP rufen dieselben Befehle auf. Getestet mit Version 0.8.0. ## Voraussetzung Der MCP-Server muss verbunden sein (Tools wie `write_range`, `read_range`, `execute_command`). Je nach Client heißen sie mit Präfix, z. B. `mcp__…__gridcraft__write_range`; sind sie zurückgestellt, erst per ToolSearch laden. Fehlen sie, dem Nutzer sagen, dass der Server nicht läuft, statt auf etwas anderes auszuweichen. **Standardweg:** GridCraft aus dem ArtCraft-Launcher und die Claude-Desktop-Erweiterung „GridCraft für Claude“ sind installiert und eingeschaltet (siehe `docs/INSTALLATION.md`). Fehlen die Tools: ArtCraft-Installation und Einstellungen → Erweiterungen prüfen, Claude komplett beenden (auch Taskleiste) und neu starten. **Alternative (Entwickler):** Eintrag `gridcraft` in `claude_desktop_config.json`; die App kann ihn beim Speichern eigener Einstellungen überschreiben. **Keine Ordnerbeschränkung:** Anders als WordCraft kennt GridCraft keine `--automation-read-root/-write-root`. Der Server kann jede Datei lesen und schreiben, die der Nutzer lesen und schreiben darf. Deshalb: - Nur Dateien öffnen, die der Nutzer genannt hat. - Nie über ein Original speichern. Immer unter neuem Namen speichern (z. B. `_bearbeitet.xlsx` im selben Ordner oder in einem vom Nutzer genannten Ausgabeordner) und den Pfad nennen. - Vor jedem `save_workbook` / `file.export*` den Zielpfad prüfen. ## Tools | Tool | Zweck | |---|---| | `list_commands` | `{search}` – Befehls-IDs mit Parametern | | `execute_command` | `{command, params}` – jeder Befehl | | `inspect_workbook` | Blätter, genutzte Bereiche, Tabellen, Diagramme, Namen, Undo-Liste | | `read_range` | `{range, sheet?, formulas?, formatted?}` – Werte, Formeln oder Anzeigetext | | `write_range` | `{range, values}` – 2-D-Array; Strings mit `=` sind Formeln | | `set_cell` / `get_cell` | eine Zelle schreiben/lesen (Wert, Formel, Text, Stil) | | `evaluate_formula` | Formel testen, ohne das Blatt zu ändern | | `format_range` | `bold, italic, underline, fontName, fontSize, fontColor, fillColor, numberFormat, horizontalAlign, wrapText, borders` | | `create_table` | `{range, name?, header?, style?}` | | `insert_chart` | `{range, type, title?, subtype?, at?}` | | `sort_range` / `filter` | Sortieren / AutoFilter | | `new_workbook` / `open_workbook` / `save_workbook` | Dateien (.xlsx, .csv, .tsv, .json, .html) | | `undo` / `redo` | Verlauf | | `list_functions` | verfügbare Tabellenfunktionen | | `screenshot` | nur im Remote-Modus (`--connect`) | Bereiche mit Blatt: `"Kalkulation!A3:E8"`. ## Arbeitsweise 1. **Befehls-IDs nie raten:** `list_commands {search: "…"}` (z. B. `column width`, `freeze`, `page`, `rename`, `chart.`). 2. **Daten in einem Rutsch:** `write_range` mit ganzer Tabelle inkl. Formeln statt vieler `set_cell`. 3. **Formeln statt fester Werte** für alles Berechnete (Summen, MwSt, Aufschläge), damit der Nutzer in Excel weiterrechnen kann. Parameter (Aufschlag, MwSt-Satz) in eigene Zellen und per absolutem Bezug (`$B$1`) verwenden. 4. **Prüfen:** `read_range` (berechnete Werte), `read_range {formulas: true}` (Formeln), `read_range {formatted: true}` (Anzeige), `inspect_workbook` (Struktur). Beim PDF-Export das Ergebnis ansehen. 5. **Speichern** als .xlsx unter neuem Namen; zur Kontrolle mit `open_workbook` wieder öffnen und Formeln lesen. ## Deutsche Eingaben – wichtigste Fallen (im Test bestätigt) - **Formeln nur englisch und mit Komma:** `=SUM(E2:E5)`, `=ROUND(E8,2)`, `=VLOOKUP(…,FALSE)`, `=IF(…)`. Deutsche Namen (`=SUMME(…)`) ergeben `#NAME?`, Semikolon als Trenner ergibt einen Formelfehler. Excel zeigt die Formeln beim Öffnen trotzdem auf Deutsch an. - **Zahlen als JSON-Zahl mit Punkt** übergeben (`0.75`, nicht `"0,75"`). Ein String mit Komma wird **als Text** gespeichert und rechnet nicht mit. - **Datumswerte als ISO** (`"2026-10-19"`) oder `=DATE(2026,10,19)`. `"19.10.2026"` wird zu Text. Danach Zahlenformat setzen: `numberFormat: "DD.MM.YYYY"`. - **Zahlenformate sind sprachneutral:** `"#,##0.00 €"` erscheint in GridCraft als `1,114.10 €`, in einem deutschen Excel aber korrekt als `1.114,10 €`. Nicht „reparieren“. - **Neue Mappe = US-Letter, Blatt heißt `Sheet1`:** für deutsche Dokumente `pageLayout.size {paper: "A4"}` und `sheet.rename {sheet: "Sheet1", name: "…"}`. - **Text, der mit `=` beginnt, wird als Formel gelesen.** Beschriftungen wie `= Materialkosten` ergeben `#NAME?`. Wie in Excel einen Apostroph voranstellen: `"'= Materialkosten"` – gespeichert wird reiner Text. ## Weitere Fallen - **Diagramme nur aus zusammenhängendem Bereich:** `insert_chart {range: "B1:B5,E1:E5"}` liefert ein leeres Diagramm über den Daten. Kategorie und Werte nebeneinander anordnen (oder Hilfsbereich anlegen) und `range: "A1:B5"` nutzen. Immer `at` setzen (z. B. `"H2"`), damit das Diagramm keine Daten verdeckt. - **PDF-Export** (`file.exportPdf {path}`) schneidet breite Inhalte ab: vorher `home.autofitColumnWidth {cols: "A:E"}`, ggf. `pageLayout.orientation {orientation: "landscape"}` und `pageLayout.scaleToFit {width: 1}`. - **Spaltenbreiten** werden nicht automatisch angepasst: nach dem Befüllen `home.autofitColumnWidth`. - **CSV-Export** (`save_workbook` mit `.csv`) schreibt Komma-getrennt und die **formatierte Anzeige** (`412.50 €`). Für deutsches Excel oder ERP-Import ungeeignet – lieber .xlsx liefern oder vor dem CSV-Export Zahlenformate entfernen und den Nutzer auf das Trennzeichen hinweisen. - **`open_workbook` öffnet eine weitere Mappe** und macht sie aktiv; Befehle wirken auf die aktive Mappe. Bei mehreren Mappen mit `inspect_workbook` prüfen, welche aktiv ist. - `undo` nach `open_workbook` hat keinen Verlauf; Fehler vor dem Speichern beheben. ## Bestehende Mappen bearbeiten Im Test blieben beim Öffnen und Speichern einer Excel-Datei erhalten: verbundene Zellen, Schrift, Zahlenformate, Kommentare, bedingte Formatierung, Datenüberprüfung, benannte Bereiche, blattübergreifende Formeln, fixierte Bereiche, Spaltenbreiten, Seitenformat (A4 quer) und Kopfzeile. Ablauf: 1. `open_workbook` → `inspect_workbook` → relevante Bereiche mit `read_range {formulas: true}` lesen, bevor etwas geändert wird. 2. Nur die gewünschten Zellen ändern; Formeln anderer Zellen nicht durch Werte ersetzen. 3. Ergebnis gegenlesen (`read_range`), unter neuem Namen speichern. 4. Dem Nutzer kurz sagen, was geändert wurde (Zellen, alter → neuer Wert), und vorschlagen, die Datei einmal in Excel zu öffnen. ## Grenzen - Keine Netzwerkfunktionen (`WEBSERVICE` liefert `#VALUE!`), keine Makros/VBA. - Funktionsumfang mit `list_functions` prüfen, bevor exotische Funktionen genutzt werden. - Im Remote-Modus (`--connect`) steuert der Server die geöffnete Desktop-App; das ist ebenfalls nicht auf Ordner beschränkt.