D2B aus einem Coding-Agenten nutzen

D2B bietet Agenten zwei Wege. MCP (Tool Calling: Claude Code / Claude Desktop / Cursor / VS Code u. a.) und die CLI (d2b: shell-getriebene Agenten, git-Sync, Batch-Arbeit). Beide zeigen dieselbe Oberfläche: JSON-Ausgabe, Fehler mit suggested_fix, Idempotenzschlüssel bei jeder Mutation, keine interaktiven Abfragen.

Die Betriebsregeln kommen vom Server. Verbindet sich ein Host per MCP, enthält die Initialisierungsantwort instructions — welches Tool wann, in welcher Reihenfolge — und derselbe Text ist als Ressource d2b://guide lesbar. Sie kopieren keine lange Anleitung ins Repo, sondern nur die Verbindung und die Wahl des Wegs (unten).

Einrichtung (was der Mensch erledigt)

1. Ein minimal berechtigtes PAT ausstellen — für einen Agenten ein Workbook-gebundenes Token mit Ratenlimit (für einen ganzen Workspace "resource": "workspace:<WS_ID>"; auch das Erstellen bleibt dort. Ein Token gehört immer zu genau einem Account; ohne account_id gilt der Standard-Account):

curl -X POST $BASE/api/v1/me/tokens -H "Authorization: Bearer $JWT" \
  -d '{"name": "agent", "scopes": ["workbooks:read", "workbooks:write"],
       "resource": "workbook:<WB_ID>", "rate_limit_per_minute": 60}'

2. Verbinden — per MCP ist Claude Code ein Befehl (andere Hosts: Per MCP verbinden):

claude mcp add d2b --transport http https://d2b.dev/mcp/ --header "Authorization: Bearer $PAT"

Die Repo-Seite schreibt d2b init — es ergänzt den AGENTS.md-Abschnitt unten und gibt den kanonischen MCP-Eintrag aus, den jeder Host übernehmen kann. Bekannte Hosts werden mit --host claude-code|cursor|vscode|codex|windsurf|claude-desktop direkt in ihre Datei gemergt, alles andere über --config PATH (JSON oder TOML). Das Token bleibt eine Umgebungsvariablen-Referenz und landet nie in einer Datei.

Für die CLI D2B_API_KEY / D2B_BASE_URL exportieren (Claude Code liest .env nicht von selbst) und mit pipx install d2b-sdk oder uvx --from d2b-sdk d2b installieren (uv add d2b-sdk + uv run d2b als Projektabhängigkeit).

Das Repo-Snippet (nur Verbindung und Wahl)

Die Regeln kommen vom Server — kopieren Sie die Anleitung nicht hierher; eine Kopie folgt neuen Tools nicht und veraltet.

## D2B
- Datenarbeit läuft über D2B. Der MCP-Server `d2b` ist verbunden — zuerst die Regeln in `d2b://guide` befolgen.
- Für git-Verwaltung (`d2b pull` / `d2b push`) und Batch-Arbeit die CLI `uvx --from d2b-sdk d2b ...` (JSON-Ausgabe; Auth aus env D2B_API_KEY / D2B_BASE_URL).
- Ziele, Dateiimport und Versionen stehen im Guide. Im Zweifel den Menschen fragen.

Die Regeln, denen ein Agent folgt (vom Server geliefert)

Der Kern von instructions / d2b://guide mit dem CLI-Gegenstück. Die Regeln hängen nicht von der Oberfläche ab; nur die Toolnamen unterscheiden sich.

Regel	MCP	CLI
Zuerst orientieren	list_my_data → get_schema	d2b workbooks list → d2b tables list --workbook WB
Ziel vor dem Erstellen beim Namen bestätigen	list_my_workspaces → create_workbook	d2b workspaces list → d2b workbooks create --workspace-id …
Dateien per Referenz einbringen (nie durch den eigenen Kontext)	ingest_url / request_upload → ingest_upload / import_cloud_file	d2b upload FILE --workbook WB --wait (d2b jobs wait JOB_ID for long runs)
Unordentliche Tabellen: Struktur prüfen, dann materialisieren	ingest_file (staged) → analyze_source → update_parse_spec → materialize_source	d2b upload --mode staged → d2b sources analyze → … materialize
Ableiten mit Transforms, nicht mit Zeilenbearbeitung	add_transform / list_transforms	d2b transforms add; d2b pull writes them to transforms/
Bei 409 neu lesen und erneut anwenden (nie blind überschreiben)	edit_version mit read_table neu lesen	edit_version mit d2b tables rows NAME --workbook WB neu lesen
An Meilensteinen eine Version schneiden	commit_snapshot / restore_snapshot / undo_op	d2b versions commit / d2b versions revert
Zahlen vor dem Berichten prüfen	review_table / review_workbook (Agent-Modus: den Job mit get_job verfolgen)	d2b review --workbook WB [--table NAME] [--agent]
Aufräumen	delete_workbook	d2b workbooks delete WB

Ein Workbook in git verwalten (CLI)

d2b pull --workbook $WB schreibt transforms/ sheets/ charts/ + d2b.json (--data TABLE ergänzt die CSV einer Basistabelle). Bearbeiten → prüfen mit d2b push --dry-run → d2b push --commit $(git rev-parse --short HEAD) → d2b.json committen. push sendet nur Änderungen (Transforms laufen erneut, data wird 3-Wege-gemergt); bei Ablehnung pull, mergen, erneut push. charts/ ist schreibgeschützt. Details: Ein Workbook in git verwalten.

Formaterhaltendes Bearbeiten (revise = nur die betroffenen Zeilen korrigieren und das Original-Excel zurückgeben)

„Das Original-Excel vollständig erhalten, nur die betroffenen Zeilen korrigieren und als neue Datei ausgeben“ gelingt mit einem einzigen revise-Aufruf (intern werden analyze → materialize → transform → Zurückschreiben zusammengefaltet). Die Berechnung bleibt als serverseitiger SQL-Transform erhalten (Lineage abrufbar); Styles, Charts, andere Sheets und Formeln außerhalb des Bereichs bleiben unangetastet.

d2b sources revise equipment.xlsx --workbook $WB \
  --transform-name merge_tokyo_sites --range A3:N8 --sheet Summary \
  --sql-file merge.sql -o output.xlsx

merge.sql ist eine {{ artifact_name }}-View ({{ src }} wird an die Tabelle des Zielbereichs gebunden). So schreibt man Aggregationen, die Zeilen zusammenfalten, korrekt:

• Additive Spalten (Stückzahlen, Fallzahlen, Beträge): SUM.
• Quoten (Auslastungsquote, Abschlussquote) nicht mitteln. Nach dem Summieren neu berechnen: SUM(分子) / NULLIF(SUM(分母), 0).
• Mittelwerte (MTBF, MTTR usw.) nicht als einfaches, sondern als gewichtetes Mittel: SUM(値 * 重み) / NULLIF(SUM(重み), 0) (das Gewicht ist eine semantisch sinnvolle Spalte wie Stückzahl oder Fallzahl).
• Kategorien (z. B. Bewertungen) über einen repräsentativen Wert: arg_max(rating, units_managed).
• Um Zeilenpositionen zu erhalten, MIN("__d2b_row_id") mit ins SELECT aufnehmen (die zusammengefasste Zeile rückt an die Position des ersten Mitglieds, frei werdende Zeilen werden an Ort und Stelle geleert; die übrigen Zeilen bewegen sich nicht).

CREATE OR REPLACE VIEW "{{ artifact_name }}" AS
SELECT
  CASE WHEN site IN ('Tokyo Site 1','Tokyo Site 2') THEN 'Tokyo' ELSE site END AS site,
  SUM(units_managed) AS units_managed,
  SUM(units_active) * 1.0 / NULLIF(SUM(units_managed), 0) AS utilization,
  SUM("MTBF(h)" * units_managed) / NULLIF(SUM(units_managed), 0) AS "MTBF(h)",
  arg_max(rating, units_managed) AS rating,
  MIN("__d2b_row_id") AS "__d2b_row_id"
FROM {{ src }}
GROUP BY 1
ORDER BY MIN("__d2b_row_id")

Enthält der Bereich Summen- oder Zwischensummenzeilen (=SUM(...)), werden diese Formelzellen nicht überschrieben, sondern bewahrt (Excel rechnet sie neu). Bearbeitungen, die mehr Zeilen erzeugen, als der Template-Bereich hat, zerstören die Geometrie und werden abgelehnt (409). In MCP ist revise_source, im SDK sources.revise(...) derselbe Pfad.

Konstanten als „lebende Formeln“ ausliefern (formula column)

Eine Spalte mit hinterlegten Konstanten (z. B. eine Auslastungsquote) lässt sich beim Export durch zeilenweise Excel-Formeln ersetzen. Die Werte selbst werden nicht angetastet — eine „Auslieferungsprojektion“, die nur mitgibt, wie sich der Wert im ausgelieferten .xlsx wieder herleiten lässt. Referenzen werden als {列名}-Platzhalter geschrieben (A1-Zelladressen sind nicht möglich — verankert an der Identität, damit Sortieren und Filtern nichts verschieben). Die Koordinaten löst der Server beim Export auf.

# Deliver utilization = units_active / units_total as a live per-row formula
d2b tables set-formula equipment utilization "{units_active} / {units_total}" --workbook <WB>

out = client.tables.set_formula(wb, "equipment", "utilization", "{units_active} / {units_total}")
out["verification"]   # {checked, rows, matches, mismatches} — does it reproduce the current constants?

Weil die Werte kanonisch sind, gibt der Schreibvorgang einen Verifikationsreport zurück (reproduziert die Formel die aktuellen Spaltenwerte innerhalb der Toleranz?). So lässt sich das „Ersetzen einer Konstante durch eine Formel“ prüfen, bevor ausgeliefert wird. In MCP: set_formula_column / list_formula_columns / clear_formula_column. Angewendet wird das derzeit beim xlsx-Export (kombinierbar mit {{ ... }}-SQL-Transforms und dem formaterhaltenden Zurückschreiben von revise). Funktionen (SUM/IF usw.) werden nur strukturell geprüft, die numerische Verifikation entfällt. underline wird nicht unterstützt.

Sheet-übergreifende Referenzen: Mit {table!column} lässt sich der gesamte Datenbereich einer Spalte in einer anderen Tabelle referenzieren (beim Export mehrerer Tabellen in eine Datei kompiliert das zu einer absoluten Referenz auf das Sheet dieser Spalte: 'rates'!$B$2:$B$N). Verwendet wird das eingepackt in eine Aggregatfunktion:

# Revenue share = this row's amount ÷ the sum of rates.weight
client.tables.set_formula(wb, "sales", "share", "{amount} / SUM({rates!weight})")
client.export.tables(wb, tables=["sales", "rates"], format="xlsx")
# → each share row compiles to =B2/SUM('rates'!$B$2:$B$N) (same-table {amount} relative, cross-refs absolute)

Ist die referenzierte Tabelle nicht im selben Export enthalten, lässt sich die Formel nicht auflösen und sie fällt auf den Wert zurück. VLOOKUP-artige Schlüssel-Joins gehören nicht in Formeln, sondern in einen JOIN-Transform (add_transform) (die Lineage bleibt erhalten).

Einschränkungen und Hinweise

• In Cloud-Sandboxes (z. B. Codex) kann wegen Egress-Beschränkungen eine Freigabe der API-Erreichbarkeit nötig sein
• Bei Agenten mit kurzen Bash-Timeouts ist der zweistufige Weg „asynchroner upload → jobs wait“ sicherer als upload --wait