86 lines
7.1 KiB
Markdown
86 lines
7.1 KiB
Markdown
---
|
||
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. `<name>_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.
|