162 lines
9.3 KiB
Markdown
162 lines
9.3 KiB
Markdown
---
|
||
name: gridcraft-mcp
|
||
description: "Excel-Arbeitsmappen (.xlsx, .xlsm, .xls, .xlsb, .ods, .csv) mit dem GridCraft-MCP-Server erstellen, öffnen, ändern, berechnen und prüfen, einschließlich Pivot-Tabellen. Verwenden, wenn GridCraft-Werkzeuge verbunden sind oder der Nutzer GridCraft nennt; typisch für Kalkulationen, Stücklisten (BOM), Listen, Diagramme, Pivot, PDF-Export. Nicht für eingebaute xlsx-Hilfen ohne GridCraft-Server."
|
||
---
|
||
|
||
# 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. CLI 0.12.1. Die Fallen weiter unten sind am 0.8.0 bestätigt und an 0.12.1 nicht erneut durchgespielt.
|
||
|
||
## Voraussetzung
|
||
|
||
Die Werkzeuge `write_range`, `read_range`, `execute_command` … müssen verbunden sein. Ihr Präfix hängt vom Client und vom Namen der Erweiterung bzw. des Servers ab (z. B. `mcp__…__GridCraft_for_Claude__write_range`). 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 etwas anderes auszuweichen.
|
||
|
||
**Keine Ordnerbeschränkung:** Anders als WordCraft kann der Server 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 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 |
|
||
| `select` | Auswahl setzen (`range`, `active?`); Befehle ohne `range` wirken darauf |
|
||
| `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` | öffnen: .xlsx, .xlsm, .xls, .xlsb, .ods, .csv, .tsv, .txt, .json; speichern: .xlsx, .csv, .tsv, .json, .html |
|
||
| `undo` / `redo` | Verlauf |
|
||
| `list_functions` | verfügbare Tabellenfunktionen |
|
||
| `screenshot` | nur mit verbundener Desktop-App |
|
||
|
||
Bereiche mit Blatt: `"Kalkulation!A3:E8"`.
|
||
|
||
## Arbeitsweise
|
||
|
||
1. **Befehls-IDs nie raten:** `list_commands {search: "…"}` (z. B. `column width`, `freeze`, `page`, `rename`, `chart.`, `range.fill`).
|
||
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. Parameter in eigene Zellen und per absolutem Bezug (`$B$1`).
|
||
4. Vor dem Massenbefüllen Formel-Syntax mit `evaluate_formula` testen.
|
||
5. **Prüfen:** `read_range`, `read_range {formulas: true}`, `read_range {formatted: true}`, `inspect_workbook`.
|
||
6. **Speichern** als .xlsx unter neuem Namen.
|
||
|
||
## Deutsche Eingaben – wichtigste Fallen
|
||
|
||
- **Formeln nur englisch und mit Komma:** `=SUM(E2:E5)`, `=ROUND(E8,2)`, `=VLOOKUP(…,FALSE)`, `=IF(…)`. Deutsche Namen ergeben `#NAME?`.
|
||
- **Zahlen als JSON-Zahl mit Punkt** (`0.75`, nicht `"0,75"`).
|
||
- **Datumswerte als ISO** (`"2026-10-19"`) oder `=DATE(2026,10,19)`. Danach `numberFormat: "DD.MM.YYYY"`.
|
||
- **Zahlenformate sind sprachneutral:** `"#,##0.00 €"` erscheint in GridCraft als `1,114.10 €`, in deutschem Excel korrekt. Nicht „reparieren“.
|
||
- **Neue Mappe = US-Letter, Blatt heißt `Sheet1`:** `pageLayout.size {paper: "A4"}` und `sheet.rename`.
|
||
- **Text, der mit `=` beginnt, wird als Formel gelesen.** Apostroph voranstellen: `"'= Materialkosten"`.
|
||
|
||
## range.fill und aktive Zelle
|
||
|
||
`range.fill {input}` interpretiert relative Bezüge **relativ zur aktiven Zelle**, nicht zur ersten Zelle des Bereichs (aus `C12` wurde fälschlich `O23`). Richtig:
|
||
|
||
1. `select {range:"M12:M111", active:"M12"}`
|
||
2. `execute_command` mit `range.fill {input:"=…C12…"}` **ohne** `range` im fill-Aufruf
|
||
|
||
Vor dem Massenbefüllen Formel mit `evaluate_formula` testen.
|
||
|
||
## Pivot (0.12.1)
|
||
|
||
`list_commands {search: "pivot"}` vor dem ersten Aufruf. Belegte IDs, Auszug:
|
||
|
||
- `insert.pivotTable` — `source` (Bereich oder Tabellenname), `destination` (`"new"` = neues Blatt, Bericht bei A3, oder `"Sheet1!H3"`), `rows`, `columns`, `values` (`{field, func?, name?}`), `filters`
|
||
- `insert.pivotChart` — Diagramm an die Pivot-Tabelle gebunden (`pivot`, `type`, `at`)
|
||
- `pivot.addField` / `pivot.removeField` / `pivot.moveField` — `area`: `rows`, `columns`, `values`, `filters`
|
||
- `pivot.refresh`, `pivot.layout` (`compact|outline|tabular`), `pivot.filter`, `pivot.sort`, `pivot.valueSettings`
|
||
|
||
## open_workbook und alreadyOpen
|
||
|
||
`.xls` bringt Werte, Formeln und Zahlenformate. `.xlsb` und `.ods` bringen Blattdaten und zwischengespeicherte Formelwerte; die Warnungen der Antwort lesen.
|
||
|
||
`open_workbook` auf eine bereits offene Datei liefert nur `{"alreadyOpen": true}` und lädt **nicht** neu – für die Kontrolle der gespeicherten Datei ungeeignet. Andere Mappe aktivieren/schließen oder Datei extern prüfen.
|
||
|
||
## Parameter-Beispiele (im Test bestätigt)
|
||
|
||
Datenüberprüfung:
|
||
```json
|
||
{"command":"data.validation","params":{"range":"E12:E100","type":"list","formula1":"\"A,B,C\"","dropdown":true,"errorStyle":"warning","errorTitle":"Eingabe","errorMessage":"Wert aus der Liste wählen"}}
|
||
```
|
||
```json
|
||
{"command":"data.validation","params":{"range":"N12:N100","type":"whole","operator":"between","formula1":"1","formula2":"9"}}
|
||
```
|
||
```json
|
||
{"command":"data.validation","params":{"range":"F12:F100","type":"decimal","operator":"greaterOrEqual","formula1":"0"}}
|
||
```
|
||
|
||
Bedingte Formatierung:
|
||
```json
|
||
{"command":"home.conditionalFormat","params":{"range":"A12:N111","rule":{"type":"expression","formula":"AND($E12<>\"\",$N12=\"\")","preset":"lightRedFill"}}}
|
||
```
|
||
```json
|
||
{"command":"home.conditionalFormat","params":{"range":"A12:A111","rule":{"type":"expression","formula":"$A12=\"x\"","style":{"font":{"bold":true}}}}}
|
||
```
|
||
|
||
Layout:
|
||
```json
|
||
{"command":"home.columnWidth","params":{"cols":"E:E","chars":36}}
|
||
{"command":"view.freezePanes","params":{"cell":"F12"}}
|
||
{"command":"pageLayout.printTitles","params":{"rows":"11:11"}}
|
||
{"command":"pageLayout.headerFooter","params":{"header":"&L&F&R&A","footer":"&LStand: &D&RSeite &P von &N"}}
|
||
```
|
||
|
||
## Weitere Fallen
|
||
|
||
- **Diagramme nur aus zusammenhängendem Bereich;** immer `at` setzen.
|
||
- **PDF-Export** schneidet breite Inhalte ab: vorher `home.autofitColumnWidth`, ggf. Querformat und `pageLayout.scaleToFit {width: 1}`.
|
||
- **CSV-Export** ist komma-getrennt und schreibt die formatierte Anzeige – für deutsches Excel oft ungeeignet.
|
||
- **`open_workbook` öffnet eine weitere Mappe** und macht sie aktiv.
|
||
- `undo` nach `open_workbook` hat keinen Verlauf.
|
||
|
||
## Bestehende Mappen bearbeiten
|
||
|
||
1. `open_workbook` → `inspect_workbook` → relevante Bereiche mit `read_range {formulas: true}` lesen.
|
||
2. Nur gewünschte Zellen ändern; Formeln anderer Zellen nicht durch Werte ersetzen.
|
||
3. Ergebnis gegenlesen, unter neuem Namen speichern.
|
||
4. Dem Nutzer kurz sagen, was geändert wurde.
|
||
|
||
## Rezepte
|
||
|
||
### Kalkulation / Zuschlagskalkulation
|
||
|
||
Parameterblatt mit Werten und absoluten Bezügen (`$B$1`). Skonto/Rabatt im Hundert korrekt formeln. Datenblatt mit `write_range`, Summen/MwSt als Formeln. A4, Zahlenformate, speichern unter neuem Namen.
|
||
|
||
### Stückliste / BOM
|
||
|
||
Kopfzeile und Zusammenfassung → Datenzeilen schreiben → Formeln per `select` + `range.fill` nachziehen → Auswahllisten (`data.validation`) → bedingte Formatierung → Freeze/PrintTitles → Revisionsblatt → speichern.
|
||
|
||
### Vorlage füllen
|
||
|
||
Vorlage öffnen → Zeilen ab Startzeile mit `write_range` schreiben → bei Bedarf `home.insertRows` → Formeln per `range.fill` nachziehen → prüfen → unter neuem Namen speichern.
|
||
|
||
## Abschlussprüfung
|
||
|
||
- `read_range` / `read_range {formulas: true}` auf Kernbereiche.
|
||
- Bei PDF: Ergebnis ansehen (Breite, Seitenumbruch).
|
||
- Gespeicherte Datei nicht mit `open_workbook` auf dieselbe Mappe „neu laden“ erwarten (`alreadyOpen`); externe Prüfung oder andere Mappe.
|
||
- Pfad dem Nutzer nennen.
|
||
|
||
## Datenschutz
|
||
|
||
- Grün: allgemeine/technische Inhalte ohne Kundenbezug.
|
||
- Gelb: Projekt-/Geschäftsinfos, Preise nur nach Abwägung oder anonymisiert.
|
||
- Rot: personenbezogene Daten und NDA-Inhalte nicht in die Cloud-KI.
|
||
- GridCraft hat keine Ordnersperre – nur Dateien öffnen/speichern, die der Nutzer genannt hat.
|
||
|
||
## Grenzen
|
||
|
||
- Keine Netzwerkfunktionen (`WEBSERVICE` liefert `#VALUE!`), keine Makros/VBA.
|
||
- Funktionsumfang mit `list_functions` prüfen.
|
||
- Mit verbundener Desktop-App (`mcp --connect PORT`, die Screenshot-Hilfe nennt 7979) entfällt jede Ordnersperre ebenfalls. Die CLI kennt keine Lese-/Schreib-Ordner.
|
||
- CLI neben MCP: `info`, `convert`, `eval`, `cat`, `check`, `run`, `commands`, `functions`, `send`, `version`.
|