コーディングエージェントから使う

D2B にはエージェント向けの経路が 2 つあります。MCP(ツールコール。Claude Code / Claude Desktop / Cursor / VS Code など)と CLI(d2b。シェル駆動のエージェント、git 同期、一括処理)。どちらでも面は同じで、出力は JSON、エラーは suggested_fix 付き、全変異に冪等キー、対話プロンプトなし。

使い方の規範はサーバーが配ります。 MCP で接続すると、初期化応答の instructions に「どのツールをどの順で使うか」の規範が入り、同じ文面が d2b://guide リソースでも読めます。リポジトリに長い手順を貼る必要はなく、貼るのは接続と経路の選択だけです(下記)。

セットアップ(人間がやること)

最小権限の PAT を発行する — エージェントに渡すトークンは workbook スコープ + レート上限を推奨(ワークスペース単位で任せるなら "resource": "workspace:<WS_ID>" — 作成もそのワークスペースに固定されます。トークンは必ず 1 アカウント宛てで、account_id を省略すると既定アカウントです):

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}'

接続する — MCP なら Claude Code は 1 コマンド(他のホストは MCP で接続する):

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

CLI なら D2B_API_KEY / D2B_BASE_URL を export し(Claude Code は .env を自動では読みません)、pipx install d2b-sdk か uvx --from d2b-sdk d2b(プロジェクト依存なら uv add d2b-sdk + uv run d2b)で入れます。

リポジトリに貼るスニペット(接続と選択だけ)

規範はサーバーから来るので、ここに手順を複製しないでください(複製はツールの追加に追随できず古びます)。

## D2B
- データは D2B で扱う。MCP サーバ `d2b` が接続済み — まず `d2b://guide` の規範に従う。
- git で管理したいとき(`d2b pull` / `d2b push`)と一括処理は CLI `uvx --from d2b-sdk d2b ...`(出力は JSON、認証は env の D2B_API_KEY / D2B_BASE_URL)。
- 作成先・取り込み方法・版の扱いは guide のとおり。迷ったら人に確認する。

エージェントが従う規範(サーバーが配る)

instructions / d2b://guide の要点と、CLI での対応です。規範は面に依存せず、道具名だけが違います。

規範	MCP	CLI
まず全体を把握する	`list_my_data` → `get_schema`	`d2b workbooks list` → `d2b tables list --workbook WB`
作成先を名前で確認してから作る	`list_my_workspaces` → `create_workbook`	`d2b workspaces list` → `d2b workbooks create --workspace-id …`
ファイルは参照で取り込む(自分のコンテキストを通さない)	`ingest_url` / `request_upload` → `ingest_upload` / `import_cloud_file`	`d2b upload FILE --workbook WB --wait`(長い処理は `d2b jobs wait JOB_ID`)
雑な表は構造を見てから実体化	`ingest_file`(staged) → `analyze_source` → `update_parse_spec` → `materialize_source`	`d2b upload --mode staged` → `d2b sources analyze` → `… materialize`
派生は行編集ではなく transform	`add_transform` / `list_transforms`	`d2b transforms add` / `d2b pull` で `transforms/` に出る
409 は読み直して再適用(自動上書きしない)	`read_table` で edit_version を取り直す	`d2b tables rows NAME --workbook WB` で edit_version を取り直す
区切りで版を切り、戻せるようにする	`commit_snapshot` / `restore_snapshot` / `undo_op`	`d2b versions commit` / `d2b versions revert`
報告の前に数字を確かめる	`review_table` / `review_workbook`(agent モードはジョブを `get_job` で待つ)	`d2b review --workbook WB [--table NAME] [--agent]`
片付ける	`delete_workbook`	`d2b workbooks delete WB`

ワークブックを git で管理する(CLI)

d2b pull --workbook $WB で transforms/ sheets/ charts/ + d2b.json が出ます(--data TABLE で base テーブルの CSV も)。編集 → d2b push --dry-run で確認 → d2b push --commit $(git rev-parse --short HEAD) → d2b.json をコミット。push は変更分だけ送り(transform は再実行、data は 3-way merge)、拒否されたら pull してマージしてから push。charts/ は読み取り専用。詳細はワークブックを git で管理する。

原本踏襲の編集(revise = 該当行だけ直して元 Excel を返す)

「元の Excel を丸ごと保ったまま、該当する行だけ直して新しいファイルで出す」は revise 1 呼び出しでできます(内部で analyze → materialize → transform → 書き戻しを畳む)。計算はサーバ側の SQL 変換に残り(lineage 取得可)、スタイル・チャート・他シート・領域外の数式はそのまま保持されます。

d2b sources revise 設備.xlsx --workbook $WB \
  --transform-name 拠点別_東京統合 --range A3:N8 --sheet サマリ \
  --sql-file merge.sql -o 出力.xlsx

merge.sql は {{ artifact_name }} ビュー({{ src }} に対象領域テーブルが束縛されます)。行を畳む集計の正しい書き方:

加算列(台数・件数・金額)は SUM。
比率(稼働率・完了率)は平均しない。合算後に再計算する: SUM(分子) / NULLIF(SUM(分母), 0)。
平均(MTBF・MTTR 等)は単純平均でなく加重平均: SUM(値 * 重み) / NULLIF(SUM(重み), 0)(重みは台数・件数など意味のある列)。
カテゴリ(評価など)は代表値: arg_max(評価, 管理台数)。
行位置を保つには MIN("__d2b_row_id") を SELECT に入れる(合算行は先頭メンバーの位置に入り、空いた行はその場で空白化。他の行は動きません)。

CREATE OR REPLACE VIEW "{{ artifact_name }}" AS
SELECT
  CASE WHEN 拠点名 IN ('東京第1拠点','東京第2拠点') THEN '東京拠点' ELSE 拠点名 END AS 拠点名,
  SUM(管理台数) AS 管理台数,
  SUM(稼働台数) * 1.0 / NULLIF(SUM(管理台数), 0) AS 稼働率,
  SUM("MTBF(h)" * 管理台数) / NULLIF(SUM(管理台数), 0) AS "MTBF(h)",
  arg_max(評価, 管理台数) AS 評価,
  MIN("__d2b_row_id") AS "__d2b_row_id"
FROM {{ src }}
GROUP BY 1
ORDER BY MIN("__d2b_row_id")

領域に合計/小計行(=SUM(...))が含まれていても、その数式セルは上書きされず温存されます(Excel が再計算)。テンプレート領域より行を増やす編集はジオメトリを壊すため拒否されます(409)。MCP では revise_source、SDK では sources.revise(...) が同じ経路です。

定数を「生きた数式」で納品する(formula column)

定数置きの列(例:稼働率)を、エクスポート時に 行ごとの Excel 数式に置き換えられます。値そのものは触らず、納品 .xlsx での再導出方法だけを付与する「配信投影」です。参照は {列名} プレースホルダで書きます(A1 セル番地は不可 — ソートやフィルタでズレないようアイデンティティに係留)。座標はエクスポート時にサーバが解決します。

# 稼働率 = 稼働台数 / 総数 を、各行で生きた式として納品
d2b tables set-formula 設備内訳 稼働率 "{稼働台数} / {総数}" --workbook <WB>

out = client.tables.set_formula(wb, "設備内訳", "稼働率", "{稼働台数} / {総数}")
out["verification"]   # {checked, rows, matches, mismatches} — 元の定数を再現するか

値が正準なので、書き込みは 検証レポートを返します(その式が現在の列値を許容誤差内で再現するか)。「定数を計算式に置き換える」を確認してから納品できます。MCP では set_formula_column / list_formula_columns / clear_formula_column。現状の適用先は xlsx エクスポート({{ ... }} の SQL 変換や revise の原本踏襲書き戻しと組み合わせ可)。関数(SUM/IF 等)は構造検証のみで数値検証はスキップ。underline は未対応。

クロスシート参照:{table!column} で別テーブルの列の全データ範囲を参照できます(複数テーブルを1ファイルにエクスポートしたとき、その列があるシートの絶対参照 'rates'!$B$2:$B$N にコンパイル)。集計関数で包んで使います:

# 売上シェア = その行の amount ÷ rates テーブルの weight 合計
client.tables.set_formula(wb, "sales", "share", "{amount} / SUM({rates!weight})")
client.export.tables(wb, tables=["sales", "rates"], format="xlsx")
# → share 列は各行 =B2/SUM('rates'!$B$2:$B$N)(同表 {amount} は相対、クロス参照は絶対)

参照先テーブルが同じエクスポートに含まれないと、その数式は解決できず値にフォールバックします。VLOOKUP 的なキー結合は数式ではなく **JOIN 変換(add_transform)**で表現してください(lineage が残ります)。

制約・注意

クラウドサンドボックス(Codex 等)では egress 制限により API 到達性の許可設定が必要な場合があります
Bash タイムアウトの短いエージェントでは upload --wait より「非同期 upload → jobs wait」の 2 段が安全です