Agent Spreadsheet MCP

agent-spreadsheet

agent-spreadsheet は、エージェントによるスプレッドシート利用のためのツール連携サービスです。

エージェントが脆弱な UI 自動化に頼らず、Excel ワークブックを読み取り、分析、変更、検証、運用するための、安全で検査可能かつトークン効率に優れた方法を提供します。

スクリーンショットを操作するだけでなく、実際のシステムのようにエージェントにスプレッドシートを扱わせたいなら、これがその基盤です。

---

このプロジェクトについて

agent-spreadsheet は、3 つの形態で統一されたスプレッドシート操作レイヤーを提供します。

形態	バイナリ／パッケージ	モード	最適な用途
CLI	agent-spreadsheet / asp	ステートレスファイル＋常駐セッション	単発のパイプライン、または複数ターンにわたるワークブック編集の保持
MCP サーバー	agent-spreadsheet-mcp	ステートフル	複数ターンにわたるエージェントセッション、ワークブックのキャッシュ、フォーク／再計算のワークフロー
TypeScript SDK	agent-spreadsheet-sdk	ライブラリ	アプリとの統合。サーバーの標準 /v1 ルートを操作するほか、組み込み WASM エンジンを通じてプロセス内で完全に実行することもできます（サーバー不要）

WASM ビルド（agent-spreadsheet-wasm）は SDK のローカルランタイムであり、独立した製品形態ではありません。JS と TypeScript のコードは 1 つのオブジェクトモデルを対象とし、実行基盤（サーバーまたは組み込みエンジン）は設定で選択します。

0.16 では、これらの形態で常駐する Rust ドキュメント／評価ランタイムと 32 操作のレジストリを共有します。明示的なネイティブセッションでは、ジャーナルを基盤とするプライベートホストが自動的に起動します。SDK／WASM と実際の just-bash セッションでは、履歴をメモリに保持します。XLSX エクスポートではドキュメントのスナップショットが保存されますが、再開可能なセッションジャーナルは保存されません。ウォーム状態での編集／再計算／読み取りループでは、XLSX のシリアライズと評価器への再取り込みを回避できます。ランタイムの保証と制限とSDK／just-bash の例をご覧ください。

対応するワークブックの形式：

• .xlsx / .xlsm — 読み取り＋書き込み
• .xls / .xlsb — 検出／読み取り中心のワークフローのみ

Formualizer を採用

プロセス内でのデフォルトの計算には、Formualizer を使用します。これは Rust で書かれた、寛容なライセンス（MIT/Apache-2.0）のスプレッドシートエンジンです。数式の解析、依存関係グラフの再計算、400 以上の Excel 関数、動的配列、エージェント向けに設計された決定論的な評価を提供します。Excel COM やヘッドレスの LibreOffice は必要ありません。オプションの LibreOffice 統合も引き続き利用できますが、リリースに不可欠なバックエンドは Formualizer です。

このネイティブエンジンにより、このプロジェクトは他の多くのエージェント向けスプレッドシートツールでは実現できない機能を提供できます。実際のワークブックを再計算し、どのセルがなぜ変わったのかを追跡して、それを証明できます。キャッシュされた値を読み取ったり、やみくもに編集を適用したりするだけではありません。

エージェントとしてワークブックを操作するのではなく、スプレッドシートのロジックを独自の製品に組み込む場合は、Formualizer を直接お使いください（Rust、Python、JS/WASM）。

---

エージェントが agent-spreadsheet を使う理由

人間だけでなく、ツール利用のために設計

• 決定論的な JSON コントラクト
• CLI 自体からスキーマと使用例を検出
• 明示的なページネーションとコンパクトな出力モード
• 機械可読な警告とエラーエンベロープ

安全な変更であり、無計画な変更ではありません

• まずドライランを実行するワークフロー
• ステートレスな出力モードと上書きの安全性
• イベントソーシングによるセッション編集
• 下流の結果を証明するための検証手段
• リスクの高いワークブック変更の前に行う構造的な影響分析

汎用的なファイル編集ではなく、スプレッドシートに特化

• 領域の検出
• テーブルとフッターを考慮した追記ヘルパー
• テンプレート行／行バンドの複製
• 数式に特化した置換と診断
• 名前付き範囲の CRUD
• 再計算＋差分＋証明のワークフロー

エージェントにとって使いやすい設計

• レガシーエイリアスとの互換性を備えたネストされたコマンドグループ
• トークン効率の高い読み取り
• セル単位の詳細な検査とレイアウト検査
• エージェントが通常間違えやすい反復作業のためのワークフローヘルパー

---

新機能／このスタックの特長

現在の機能は、単なる「いくつかのセルを読み取る」ツールを大きく上回っています。主な機能は次のとおりです。

• 主な CLI としてのasp。互換性エイリアスとしてagent-spreadsheetも維持しています
• asp verify proofとasp verify diffによるグループ化された検証
• 次の操作に対応するプレビュー優先のワークフローヘルパー：
  • write append
  • write clone-template-row
  • write clone-row-band
• 解析ポリシー診断を備えた数式の安全な一括ワークフロー
• セル／レイアウト／エクスポート／インポートの検査機能
• 名前付き範囲の管理（write name define|update|delete）
• 数式のみの置換（write formulas replace）
• ログ、ブランチ、取り消し／やり直し、フォーク、適用、マテリアライズに対応したイベントソーシングによるセッション編集
• コントラクト駆動のスプレッドシート自動化に対応するSheetPort マニフェストのライフサイクルと実行

---

インストール

シェルインストーラー

curl -fsSL https://raw.githubusercontent.com/PSU3D0/agent-spreadsheet/main/install.sh | sh

インストーラーは、ビルド済み CLI を~/.local/binにダウンロードし、aspコマンドを作成します。ASP_VERSION=0.16.0でリリースを固定し、ASP_INSTALL_DIRで別のインストール先を指定するか、--mcpを渡して MCP サーバーもインストールできます。

curl -fsSL https://raw.githubusercontent.com/PSU3D0/agent-spreadsheet/main/install.sh | sh -s -- --mcp

npm

npm i -g agent-spreadsheet

ビルド済みのネイティブバイナリから、asp（主なコマンド）とagent-spreadsheet（互換性エイリアス）の両方をインストールします。Rust ツールチェーンは不要です。

cargo-binstall

cargo binstall agent-spreadsheet

ビルド済み CLI を数秒でインストールできます。

Cargo

cargo install agent-spreadsheet --features recalc --bin asp --bin agent-spreadsheet

CLI をソースからビルドします。Formualizer（ネイティブの再計算エンジン）がデフォルトで含まれます。

mise

mise use -g "ubi:PSU3D0/agent-spreadsheet[exe=asp]"

# Homebrew
brew install psu3d0/tap/agent-spreadsheet

MCP サーバー

cargo install agent-spreadsheet-mcp

Docker

# Read-only / slim
docker pull ghcr.io/psu3d0/agent-spreadsheet-mcp:latest

# Write + recalc + screenshots
docker pull ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full

JavaScript SDK

npm i agent-spreadsheet-sdk

ビルド済みバイナリ

GitHub Releasesから、バイナリとアーカイブをダウンロードできます。

公開されているネイティブアセット：

• Linux x86_64
• Linux arm64
• macOS x86_64
• macOS arm64
• Windows のネイティブバイナリは0.16では提供されません。ネイティブリリースの検証対象は Linux と macOS です

---

まずはこちら：主なワークフロー

1) セルを読み取る前にワークブックの構成を把握する

# What sheets are here?
asp read sheets data.xlsx

# What regions/tables/parameter blocks does this sheet contain?
asp read overview data.xlsx "Model"

# What named items are available?
asp read names data.xlsx

# Read a structured region as a table
asp read table data.xlsx --sheet "Model"

2) エージェントに必要な情報を正確に検査する

# Raw values for exact ranges
asp read values data.xlsx Model A1:C20

# Detail-view for targeted cells (value / formula / cached / style triage)
asp read cells data.xlsx Model B2 D10:F12

# Layout-aware rendering for a bounded range
asp read layout data.xlsx Model --range A1:H30 --render both

# Export a bounded range to csv or grid json
asp read export data.xlsx Model A1:H30 --format csv --output model.csv

3) 安全なステートレス編集 → 再計算 → 証明 → 差分のループを実行する

asp workbook copy data.xlsx /tmp/draft.xlsx
asp write cells /tmp/draft.xlsx Inputs "B2=500" "C2==B2*1.1"
asp workbook recalculate /tmp/draft.xlsx
asp verify proof data.xlsx /tmp/draft.xlsx --targets Summary!B2,Summary!B3 --named-ranges
asp verify diff data.xlsx /tmp/draft.xlsx --details --limit 50

代表的なラベルモードの検索例：

asp analyze find-value data.xlsx "Net Income" --mode label --label-direction below

4) ワークブックを変更する前に構造的なリスクをプレビューする

asp analyze ref-impact data.xlsx --ops @structure_ops.json --show-formula-delta

これは意図的に読み取り専用です。シフトした範囲、絶対参照に関する警告、トークン数、および任意の変更前／変更後の数式サンプルを表示します。

5) 行の処理を独自に作り直すのではなく、ワークフローヘルパーを使う

# Stateless batch writes
asp write batch transform data.xlsx --ops @ops.json --dry-run
asp write batch style data.xlsx --ops @style_ops.json --dry-run

# Append rows into a detected region or table, respecting footer rows when present
asp write append data.xlsx --sheet Revenue --table-name RevenueTable --from-csv rows.csv --header --dry-run

# Clone one template row with preview-first planning
asp write clone-template-row data.xlsx --sheet Inputs --source-row 8 --after 8 --count 3 --dry-run

# Clone a contiguous row band repeatedly
asp write clone-row-band data.xlsx --sheet Forecast --source-rows 12:16 --after 16 --repeat 4 --dry-run

6) 編集が複雑になったら、ステートフルセッションを使う

asp session start --base data.xlsx --workspace .
asp session op --session <id> --ops @edit.json --workspace .
asp session apply --session <id> <staged_id> --workspace .
asp session materialize --session <id> --output result.xlsx --workspace .

適切な履歴とブランチが必要な場合：

asp session log --session <id> --workspace .
asp session fork --session <id> scenario-a --workspace .
asp session undo --session <id> --workspace .
asp session redo --session <id> --workspace .
asp session checkout --session <id> <op_id> --workspace .

7) SheetPort でワークブックのインターフェイスをコントラクトにする

# Discover candidate ports from workbook structure
asp sheetport manifest candidates model.xlsx

# Validate or normalize a manifest
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml

# Bind-check a workbook against a manifest
asp sheetport bind-check model.xlsx manifest.yaml

# Execute the manifest with JSON inputs
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json

---

CLI の概要

主な CLI は**asp**です。

agent-spreadsheetも互換性エイリアスとして引き続き使用できるため、次のどちらも有効です。

asp read sheets data.xlsx
agent-spreadsheet read sheets data.xlsx

推奨されるコマンドグループ

• asp read ...
• asp analyze ...
• asp write ...
• asp workbook ...
• asp verify ...
• asp session ...
• asp sheetport ...

レガシーエイリアス

従来のフラットなコマンドは、可能な範囲で引き続き新しいネスト構造に正規化されます。これにより、古いプロンプト、ドキュメント、自動化からの移行が容易になります。

CLI に組み込まれた発見可能性

エージェントがペイロードの形式に迷った場合は、ツールに直接問い合わせることができます。

asp operations                  # CLI-supported runtime subset
asp registry --all              # complete host-independent registry + schemas
asp schema read_cells
asp example read_cells
asp schema write batch transform
asp example write batch transform
asp schema session op transform.write_matrix
asp example session op transform.write_matrix

正規の機械呼び出しでは、ほかのインターフェースと同じレジストリおよびディスパッチャーを使用します。asp schema <canonical-op> と asp example <canonical-op> では、ネイティブアダプターの契約が表示されます。--bind と --baseline が一時的なリソースを注入するため、resource_id と、検証の場合の baseline_resource_id は必須の JSON から省かれます。ホストに依存しない asp registry --all に変更はありません。

asp op read_cells --bind data.xlsx --json '{"sheet_name":"Sheet1","selection":{"kind":"range","ranges":["A1:C10"]}}'
asp op verify_workbook --baseline base.xlsx --bind current.xlsx --json '{}'
echo '{"action":"schema"}' | asp op sheetport_manifest

--bind は現在のワークブックを読み込みます。一方、--baseline が2つ目のワークブックを渡すのは verify_workbook の場合のみです。正規の変更可能な CLI 呼び出しでは、永続化先を必ず1つだけ指定する必要があります。--output <path> は新しいファイルを書き込み、--in-place はバインドされたファイルをアトミックに置き換えます。純粋なプレビューでは何も永続化せず、どちらも受け付けません。永続的なフォーク、チェックポイント、ステージ、履歴の操作は、ステートレスな CLI の検出機能から意図的に除外されています。これは中核となる設計原則です。インターフェースはエージェント自身に説明するべきです。

---

コマンドファミリー

read — 抽出と検査

コマンド	目的
asp read sheets <file>	シートを要約メタデータとともに一覧表示
asp read overview <file> <sheet>	領域、ヘッダー、方向を検出
asp read values <file> <sheet> <range> [range...]	A1 形式で指定した範囲の生の値を取得
asp read export <file> <sheet> <range>	指定範囲を csv または grid json としてエクスポート
asp read cells <file> <sheet> <target> [target...]	値、数式、キャッシュ、スタイルのスナップショットでセルや範囲を検査
asp read page <file> <sheet> ...	next_start_row を使用した決定論的なシートのページ分割
asp read table <file> ...	next_offset を使用した決定論的な構造化テーブル／領域の読み取り
asp read names <file>	名前付き範囲、名前付き数式、テーブル項目
asp read workbook <file>	ワークブックレベルのメタデータ
asp read layout <file> <sheet>	列幅、結合、罫線、任意の ASCII 出力に対応したレイアウト考慮型の表示

エージェントにとって重要な理由

エージェントが「スプレッドシート全体」を必要とすることはほとんどありません。必要なのは、次のものです。

• 適切な領域
• 適切なページ
• 適切なセル
• 意図を理解するのに必要な最小限のレイアウト情報

そのため、読み取りインターフェースは領域の検出、構造化された読み取り、詳細な検査、明示的な続行を組み合わせています。

---

analyze — 検索、診断、影響の把握

コマンド	目的
asp analyze find-value <file> <query>	値またはラベルの意味に基づいて検索
asp analyze find-formula <file> <query>	数式内のテキストを検索
asp analyze formula-map <file> <sheet>	複雑さ／頻度別に数式を要約
asp analyze formula-trace <file> <sheet> <cell> <precedents|dependents>	続行に対応した依存関係の追跡
asp analyze scan-volatiles <file>	揮発性関数を含む数式を検索
asp analyze sheet-statistics <file> <sheet>	密度と型の統計
asp analyze table-profile <file>	ヘッダー、型、カーディナリティのプロファイリング
asp analyze ref-impact <file> --ops @structure_ops.json	変更を加えずに、構造編集の影響を事前確認

これが重要な理由

ヘッドレスのスプレッドシート自動化が真価を発揮するのは、変更を実行するだけでなく、その結果を説明できるときです。ref-impact、formula-trace、グループ化された診断は、いずれもそのための機能です。

---

write — 安全な変更とワークフローヘルパー

コマンド	目的
asp write cells <file> <sheet> ...	セルを直接編集する簡易コマンド
asp write import <file> <sheet> ...	グリッド形式の JSON または CSV をワークブックの範囲にインポート
asp write append ...	フッターを考慮し、領域またはテーブルに行を追加
asp write clone-template-row ...	プレビューを優先した計画に基づき、テンプレート行を複製
asp write clone-row-band ...	複数行のテンプレート範囲を繰り返し複製
asp write formulas replace ...	シートまたは範囲内で数式のみを検索して置換
`asp write name define	update
asp write batch transform ...	ステートレスな変換パイプライン
asp write batch style ...	ステートレスなスタイル編集
asp write batch formula-pattern ...	オートフィルのように数式を適用
asp write batch structure ...	行／列／シートの構造変更、コピー、移動
asp write batch column-size ...	列幅の操作
asp write batch sheet-layout ...	ウィンドウ枠の固定、ズーム、ページ設定、印刷範囲
asp write batch rules ...	データの入力規則と条件付き書式

安全性モデル

ほとんどの変更コマンドは、厳密なモードの組み合わせに対応しています。

• --dry-run
• --in-place
• --output <PATH>

エージェントにとって重要なのは、次のことが可能になるためです。

• ドライランによる計画
• 非破壊的な実行
• 明示的な上書き制御

数式のメンテナンス

数式の変更が、正式にサポートされる機能になりました。

asp write formulas replace data.xlsx Sheet1 --find '$64' --replace '$65' --dry-run
asp write formulas replace data.xlsx Sheet1 --find 'Sheet1!' --replace 'Sheet2!' --range A1:Z100 --output fixed.xlsx

名前付き範囲のメンテナンス

asp write name define data.xlsx RevenueInput 'Inputs!$B$2'
asp write name update data.xlsx RevenueInput 'Inputs!$B$2:$B$4' --in-place
asp write name delete data.xlsx RevenueInput --in-place

---

workbook — ファイルレベルのフロー

コマンド	目的
asp workbook create <path>	新しいワークブックを作成
asp workbook copy <source> <dest>	編集ワークフロー向けの安全なコピー
asp workbook recalculate <file>	設定済みのバックエンドを使って数式を再計算

---

verify — 雰囲気ではなく、確かな検証

コマンド	目的
asp verify proof <baseline> <current>	対象の差分を検証し、新規／解消済み／既存のエラーを切り分け
asp verify diff <original> <modified>	必要に応じてページ分割した詳細を表示できる、概要優先のグループ化されたワークブック差分

検証が重要な理由

ほとんどのスプレッドシート自動化ツールは、「編集を適用しました」で終わります。

agent-spreadsheet はさらに踏み込みます。

• 対象のセルは期待どおりに変更されたか？
• ワークブックに新たなエラーが発生していないか？
• どの変更が直接編集によるもので、どれが再計算の影響によるものか？
• 全体として何が変わったのか、エージェントが判断できるようにグループ化するとどうなるか？

この検証レイヤーは、このプロジェクトが単なるユーティリティスクリプトではなく、本格的なエージェント基盤である理由の大きな部分を占めています。

---

session — イベントソーシングによるステートフルな編集

セッション機能は、単一のステートレスな書き込みでは複雑すぎるワークフロー向けです。

セッションでできること

• 永続的な編集状態
• ステージングされたドライラン操作
• 比較交換方式の適用セマンティクス
• ログと再生機能
• ブランチ／切り替え／フォークのフロー
• 元に戻す／やり直す／チェックアウト
• ワークブックファイルへの明示的な反映

基本的なループ

asp session start --base model.xlsx --workspace .
asp session op --session <id> --ops @ops.json --workspace .
asp session apply --session <id> <staged_id> --workspace .
asp session materialize --session <id> --output result.xlsx --workspace .

履歴とブランチ

asp session log --session <id> --workspace .
asp session branches --session <id> --workspace .
asp session fork --session <id> experiment-b --workspace .
asp session switch --session <id> experiment-b --workspace .
asp session undo --session <id> --workspace .
asp session redo --session <id> --workspace .
asp session checkout --session <id> <op_id> --workspace .

再現性、監査可能性、複数ステップにわたる安全性を求める場合は、セッションを使用してください。

---

sheetport — 実行可能な契約としてのスプレッドシートインターフェース

SheetPort は、ワークブックの入力／出力を明示的な機械可読の契約に変換するためのワークフロー機能です。

マニフェストのライフサイクル

asp sheetport manifest candidates model.xlsx
asp sheetport manifest schema
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml

バインドの確認と実行

asp sheetport bind-check model.xlsx manifest.yaml
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json --freeze-volatile

ワークブックを不透明なファイルではなく、宣言されたサービスインターフェースのように機能させたい場合に使用してください。

---

エージェント向け出力契約

標準形式とコンパクト形式

すべてのコマンドはデフォルトで JSON を使用します。多くのコマンドは次もサポートしています。

--shape canonical
--shape compact

ポリシー：

• canonical は完全で安定したスキーマを維持します
• compact は、契約で許可される範囲でラッパーの冗長性を削除しつつ、継続フィールドとコマンド固有のセマンティクスを保持します

形式のポリシー：

• Canonical（デフォルト）： 完全なレスポンススキーマを保持します。
• range-values： canonical モードと compact モードの両方で、安定した values: [...] エンベロープを返します。
• range-values のデフォルトエンコーディング： 密な JSON（dense.encoding = "dense_v1"）で、dictionary とランレングス形式の row_runs を使用します。
• range-values の --include-formulas： dense モードでは疎な数式座標（dense.formulas）を含め、明示的な json 形式では行列を含めます。
• read-table と sheet-page：compact ではアクティブな分岐と継続フィールド（next_offset、next_start_row）が保持されます。
• formula-trace compact： layers と next_cursor を保持しつつ、レイヤーごとの highlights を省略します。

決定論的なページネーションループ

# sheet-page continuation
asp read page data.xlsx Sheet1 --format compact --page-size 200
asp read page data.xlsx Sheet1 --format compact --page-size 200 --start-row 201

# read-table continuation
asp read table data.xlsx --sheet "Sheet1" --table-format values --limit 200 --offset 0
asp read table data.xlsx --sheet "Sheet1" --table-format values --limit 200 --offset 200

sheet-page のマシンコントラクト

• ペイロードフィールドを読み取る前に、トップレベルの format を確認します。
• format=full：トップレベルの rows と、任意の header_row および next_start_row を読み取ります。
• format=compact：compact.headers、compact.header_row、compact.rows と、任意の next_start_row を読み取ります。
• format=values_only：values_only.rows と、任意の next_start_row を読み取ります。
• 継続処理は、トップレベルに next_start_row がある場合、常にその値に基づいて行います。
• グローバルな --shape compact は、アクティブな sheet-page の分岐を保持します。sheet-page のペイロードをフラット化することはありません。

マシンによる継続処理の例：

1. --start-row を指定せずに 1 ページ目をリクエストします。
2. next_start_row がある場合は、--start-row <next_start_row> を指定して sheet-page を再度呼び出します。
3. next_start_row が省略されたら停止します。

自己記述型ペイロード

送信する内容がわからない場合は、スキーマまたは例を要求します。

asp schema write batch rules
asp example write batch rules
asp schema session op structure.insert_rows
asp example session op structure.insert_rows

バッチペイロードの例

すべてのバッチペイロードは、トップレベルのエンベロープオブジェクトを使用します。ほとんどのコマンドでは {"ops":[...]} が必要です。column-size-batch では {"sheet_name":"...","ops":[...]} が推奨されます。また、{"ops":[...]} 内の各操作に sheet_name を指定する形式も受け付けます。

transform-batch のペイロード（@transform_ops.json）

• 最小構成：{"ops":[{"kind":"fill_range","sheet_name":"Sheet1","target":{"kind":"range","range":"B2:B4"},"value":"0"}]}
• 高度な例：{"ops":[{"kind":"replace_in_range","sheet_name":"Sheet1","target":{"kind":"region","region_id":1},"find":"N/A","replace":"","match_mode":"contains","case_sensitive":false,"include_formulas":true}]}

style-batch のペイロード（@style_ops.json）

• 最小構成：{"ops":[{"sheet_name":"Sheet1","target":{"kind":"range","range":"B2:B2"},"patch":{"font":{"bold":true}}}]}
• 高度な例：{"ops":[{"sheet_name":"Sheet1","target":{"kind":"cells","cells":["B2","B3"]},"patch":{"number_format":"$#,##0.00","alignment":{"horizontal":"right"}},"op_mode":"merge"}]}

write batch の数式パターンペイロード（@formula_ops.json）

• 最小構成：{"ops":[{"sheet_name":"Sheet1","target_range":"C2:C4","anchor_cell":"C2","base_formula":"B2*2"}]}
• 高度な例：{"ops":[{"sheet_name":"Sheet1","target_range":"C2:E4","anchor_cell":"C2","base_formula":"B2*2","fill_direction":"both","relative_mode":"excel"}]}
• relative_mode の有効な値：excel、abs_cols、abs_rows

structure-batch のペイロード（@structure_ops.json）

• 最小構成：{"ops":[{"kind":"rename_sheet","old_name":"Summary","new_name":"Dashboard"}]}
• 高度な例：{"ops":[{"kind":"copy_range","sheet_name":"Sheet1","dest_sheet_name":"Summary","src_range":"A1:C4","dest_anchor":"A1","include_styles":true,"include_formulas":true}]}

column-size-batch のペイロード（@column_size_ops.json）

• 最小（推奨）：{"sheet_name":"Sheet1","ops":[{"range":"A:A","size":{"kind":"width","width_chars":12.0}}]}
• 高度（推奨）：{"sheet_name":"Sheet1","ops":[{"target":{"kind":"columns","range":"A:C"},"size":{"kind":"auto","min_width_chars":8.0,"max_width_chars":24.0}}]}
• こちらも受け付けます（統一された形式）：{"ops":[{"sheet_name":"Sheet1","range":"A:A","size":{"kind":"width","width_chars":12.0}}]}

sheet-layout-batch のペイロード（@layout_ops.json）

• 最小：{"ops":[{"kind":"freeze_panes","sheet_name":"Sheet1","freeze_rows":1,"freeze_cols":1}]}
• 高度：{"ops":[{"kind":"set_page_setup","sheet_name":"Sheet1","orientation":"landscape","fit_to_width":1,"fit_to_height":1}]}

rules-batch のペイロード（@rules_ops.json）

• 最小：{"ops":[{"kind":"set_data_validation","sheet_name":"Sheet1","target_range":"B2:B4","validation":{"kind":"list","formula1":"\"A,B,C\""}}]}
• 高度：{"ops":[{"kind":"set_conditional_format","sheet_name":"Sheet1","target_range":"C2:C10","rule":{"kind":"expression","formula":"C2>100"},"style":{"fill_color":"#FFF2CC","bold":true}}]}

write batch formula-pattern は、対象となる数式セルのキャッシュ済み結果をクリアします。計算値を更新するには、workbook recalculate を実行してください。

数式の解析ポリシー

数式対応コマンドでは、次の設定を利用できます。

--formula-parse-policy fail|warn|off

• fail — 中止します
• warn — 続行し、診断情報をまとめて付加します
• off — 警告なしでスキップします

これにより、エージェントはワークフローに応じて厳密さと進行のどちらを優先するか選べます。

CLI リファレンスの抜粋

• read values <file> <sheet> <range> [range...] [--format dense\|json\|values\|csv] [--include-formulas]
• read cells <file> <sheet> <target> [target...] [--include-empty]
• read page <file> <sheet> --format <full|compact|values_only> [--start-row ROW] [--page-size N]
• workbook create <path> [--sheets Inputs,Calc,...] [--overwrite]
• analyze find-value <file> <query> [--sheet S] [--mode value\|label] [--label-direction right\|below\|any]
• write batch transform <file> --ops @ops.json (--dry-run\|--in-place\|--output PATH)

数式書き込みパスの来歴（write_path_provenance）

数式を書き込むコマンドは、トラブルシューティング用に任意の来歴メタデータを出力します。

• written_via：書き込みパス（edit、transform_batch、apply_formula_pattern）
• formula_targets：数式の書き込みで変更されたシート／セルまたはシート／範囲の対象

デバッグ時の比較ワークフロー：

1. 同じ数式対象を、2つの異なるパスで適用します。
2. 応答内の write_path_provenance.written_via と formula_targets を比較します。
3. inspect-cells と recalculate を使用して、結果の動作を比較します。

財務表示の初期設定

• はみ出しを防ぐため、ラベル列（多くの場合、列A）の幅を明示的に設定します（およそ 24–36 文字）。
• 意味上の種類に応じて、統一した数値形式を適用します。
  • 通貨："$"#,##0.00_);[Red]("$"#,##0.00)
  • パーセント：0.0%
  • 整数／件数：#,##0
• ヘッダーの配置が確定した後に、sheet-layout-batch の固定ペインを適用します。

JSON の出力はデフォルトでコンパクトです。警告を非表示にするには、--quiet を使用してください。 グローバルな --output-format csv は現在サポートされていません。read table --table-format csv のような、コマンド固有の CSV オプションを使用してください。

---

MCP サーバーのクイックスタート

MCP インターフェースは、agent-spreadsheet のステートフルなサーバー版です。

次の用途で使用します。

• 呼び出し間でのワークブックのキャッシュ
• ステートレスなファイル置換ではなく、フォークのライフサイクル管理
• 複数ターンにわたるエージェントのワークフロー
• スクリーンショットや、より高度なサーバー側オーケストレーション

Claude Code / Claude Desktop

~/.claude.json またはプロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "spreadsheet": {
      "command": "agent-spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

Docker

{
  "mcpServers": {
    "spreadsheet": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/workbooks:/data",
        "ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full",
        "--transport", "stdio"
      ]
    }
  }
}

:latest は読み取り専用のスリムイメージです（書き込み／フォーク／再計算ツールは無効です）。:latest-full には、書き込みツールと再計算機能（LibreOffice を使用）が含まれています。

HTTP モード

agent-spreadsheet-mcp --workspace-root /path/to/workbooks
# -> http://127.0.0.1:8079  (POST /mcp, and the canonical route under /v1)

同じプロセスでは、MCP を話さないプログラムクライアント向けに、プレーンな標準 HTTP ルートも提供しています。

ルート	用途
POST /v1/op/{operation}	標準操作を実行します。リクエストボディは標準入力オブジェクト、レスポンスは標準エンベロープです
GET /v1/operations	このプロセスで実行時にフィルタリングされた操作一覧を取得します
GET /v1/registry	エラースキーマを含む標準レジストリの全体投影を取得します
GET /v1/artifacts/{handle}	screenshot_sheet が生成した artifact:sha256:<hex> ハンドルのバイトデータを取得します

curl -sS -X POST http://127.0.0.1:8079/v1/op/list_workbooks -d '{}'

標準エラーは、エラーコードに対応するステータスの標準エラーエンベロープを返します（400 無効なリクエスト、404 不明な操作／リソース、409 リビジョンの競合、500 操作の失敗、501 機能を利用できません）。/mcp と同様に、/v1 に認証はありません。ループバックのデフォルトバインドがセキュリティ境界です。詳しくはdocs/architecture/canonical-http-route.mdを参照してください。

設定

すべての設定は、CLI フラグ（agent-spreadsheet-mcp --help）、環境変数、または設定ファイルのキー（--config file.yaml）で指定できます。CLI の設定は設定ファイルより優先されます。

変数	デフォルト	説明
SPREADSHEET_MCP_WORKSPACE	.	スプレッドシートファイルを格納するワークスペースのルート
SPREADSHEET_MCP_WORKBOOK	なし	サーバーを単一のブックパスに固定します
SPREADSHEET_MCP_EXTENSIONS	xlsx,xlsm,xls,xlsb	許可するブック拡張子のカンマ区切りリスト
SPREADSHEET_MCP_ENABLED_TOOLS	すべてのツール	指定したツール名（カンマ区切り）のみに実行を制限します
SPREADSHEET_MCP_TRANSPORT	http	公開するトランスポート（http または stdio）
SPREADSHEET_MCP_HTTP_BIND	127.0.0.1:8079	http トランスポート使用時の HTTP バインドアドレス
SPREADSHEET_MCP_RECALC_ENABLED	false	書き込み／再計算ツールを有効にします（デフォルトではネイティブの Formualizer バックエンドを使用）
SPREADSHEET_MCP_RECALC_BACKEND	auto	再計算バックエンドの優先設定：auto、formualizer、または libreoffice
SPREADSHEET_MCP_MAX_CONCURRENT_RECALCS	2	同時に実行する LibreOffice インスタンスの最大数
SPREADSHEET_MCP_VBA_ENABLED	false	VBA のイントロスペクションツールを有効にします（読み取り専用）
SPREADSHEET_MCP_ALLOW_OVERWRITE	false	save_fork による元のブックファイルの上書きを許可します
SPREADSHEET_MCP_CACHE_CAPACITY	5	メモリに保持するブックの最大数
SPREADSHEET_MCP_TOOL_TIMEOUT_MS	30000	ツールリクエストのタイムアウト（ミリ秒）
SPREADSHEET_MCP_MAX_RESPONSE_BYTES	1000000	レスポンスの最大サイズ（バイト）
SPREADSHEET_MCP_MAX_PAYLOAD_BYTES	65536	切り詰める前のツールペイロードの最大サイズ（バイト）
SPREADSHEET_MCP_MAX_CELLS	10000	切り詰める前のツールペイロードあたりのセルの最大数
SPREADSHEET_MCP_MAX_ITEMS	500	切り詰める前のツールペイロードあたりの項目の最大数
SPREADSHEET_MCP_OUTPUT_PROFILE	token_dense	ツールレスポンスの出力プロファイル（token_dense または verbose）
SPREADSHEET_MCP_SLIM_SURFACE	true	標準専用ルーターです。false に設定すると、従来の 0.13 のツール名が追加されます
SPREADSHEET_MCP_SCREENSHOT_DIR	<workspace_root>/screenshots	スクリーンショットの PNG を書き込むディレクトリ
SPREADSHEET_MCP_PATH_MAP	なし	レスポンスにクライアントから見えるパスを含めるパスマッピング INTERNAL=CLIENT（カンマ区切り。Docker のボリュームマウントで便利です）

タイムアウト／制限の各変数（TOOL_TIMEOUT_MS、MAX_RESPONSE_BYTES、MAX_PAYLOAD_BYTES、MAX_CELLS、MAX_ITEMS）に 0 を設定すると、その制限は無効になります。

---

MCP ツールの構成

デフォルトの MCP ルーターは、正式な操作レジストリから生成されます。書き込み可能な基本構成では、27 個の操作が公開されます。内訳は、検出／読み取り／分析操作が 17 個、書き込み／ライフサイクル操作が 10 個です。機能に対応したデプロイでは、screenshot_sheet、sheetport_manifest、execute_sheetport、inspect_vba を追加でき、最大 31 個になります。正式な操作のうち 19 個は読み取り専用です。

各ツールは、レジストリ記述子の閉じた入力スキーマを使用し、正式な schema_version / operation / resource_id / revision_id / data エンベロープを返します。revision_id はワークブックのセル内容のバイト列だけでなく、リソースの観測可能な完全な状態を識別します。再計算、評価／来歴の状態、またはライフサイクルメタデータによって、内容を編集しなくても進む場合があります。クライアントは、内容のハッシュを計算または保持するのではなく、比較交換、カーソル、新しさの判断に、最新の応答エンベロープに含まれるリビジョンを使用する必要があります。静的な MCP アノテーションでは記述子の最悪ケースのリスクが示され、説明ではアクション固有のリスクが示されます。close_workbook はランタイム管理にあたるため、対象外です。

操作の完全な一覧とコントラクトについては、正式な操作一覧を参照してください。互換性を保つための 1 期間に限り、従来の 0.13 名を追加するには、SPREADSHEET_MCP_SLIM_SURFACE=false を設定してください。互換モードでは、共通の名前は従来のスキーマとエンベロープを使用し、一度だけ登録されます。

JS SDK

agent-spreadsheet-sdk は、アプリ向けの統合レイヤーです。JS/TS コードが対象とする単一のインターフェイスです。

生成された正式な便利メソッド、従来の入力エイリアス、変更されない正式なエンベロープ、型付き機能エラーを提供します。31 操作の完全なマニフェストがスキーマとメソッドを提供し、利用可能な機能は常に選択したライブバックエンドから取得されます。

バックエンドは設定上の選択肢であり、別々の API ではありません。

• MCP バックエンド — 稼働中の agent-spreadsheet-mcp サーバーに接続します（共有状態、フォーク、複数クライアント）
• 組み込み WASM バックエンド — エンジンがワークブックのバイト列上でプロセス内実行されます。サーバーやファイルシステムは不要です（ブラウザー、Node、サーバーレス）。このリポジトリの agent-spreadsheet-wasm クレートは、このバックエンドのビルド成果物です。SDK の内部依存関係であり、直接使用するパッケージではありません。

インストール：

npm i agent-spreadsheet-sdk

バックエンドの状態：MCP バックエンドは安定しており、ライブツール検出（または明示的な supportedOperations リスト）を通じて操作をネゴシエートします。組み込み WASM バックエンドは、生成されたバインディングの operations() 記述子からサポート状況を取得し、CI では実際の wasm-bindgen Node パッケージを使ってテストされています。

---

再計算バックエンド

数式の再計算は、プラグインで切り替えられます。

バックエンド	方法	デフォルト	最適な用途
Formualizer	ネイティブ Rust エンジン	はい	外部依存なしで高速に再計算するデフォルト設定
LibreOffice	ヘッドレス soffice	Docker :latest-full ／明示的なビルド	最大限の互換性とスクリーンショットのワークフロー

機能に関する注意：

• recalc-formualizer はデフォルトで有効です
• recalc-libreoffice は LibreOffice 対応ビルドで利用できます
• 再計算なしでも、読み取りや多くの書き込みのワークフローは引き続き動作します。バックエンドが必要なのは、再計算自体のみです

---

Docker イメージ

公開先：ghcr.io/psu3d0/agent-spreadsheet-mcp

イメージ	サイズ	再計算	最適な用途
latest	約 15 MB	なし	読み取り専用の分析と軽量なエージェントのデプロイ
latest-full	約 800 MB	あり	書き込み＋再計算＋スクリーンショット

例：

# Read-only
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/agent-spreadsheet-mcp:latest

# Write + recalc
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full

---

ワークスペースの構成

agent-spreadsheet/
├── crates/
│   ├── agent-spreadsheet/        # shared engine + asp / agent-spreadsheet CLI
│   ├── agent-spreadsheet-mcp/        # MCP server adapter
│   └── agent-spreadsheet-wasm/   # experimental WASM-facing wrapper
├── npm/
│   ├── agent-spreadsheet/      # npm CLI wrapper
│   └── agent-spreadsheet-sdk/    # JS SDK
├── docs/                       # architecture and design docs
├── benchmarks/                 # scenario budget regression harnesses
└── .github/workflows/          # CI, release, docker builds

パッケージの役割

パッケージ	役割
agent-spreadsheet	共有エンジンと CLI バイナリ
agent-spreadsheet-mcp	ステートフルな MCP トランスポートとサーバーインターフェイス
agent-spreadsheet-wasm	WASM 向けのバイト列／セッションラッパー
agent-spreadsheet	CLI バイナリ用の npm ラッパー
agent-spreadsheet-sdk	MCP/WASM 形式の統合向け JS SDK

---

アーキテクチャに関するメモ

主な考え方：

• CLI、MCP、セッション、WASM 向けの処理で共有する単一のセマンティックコア
• 構造を把握するための領域検出
• エージェントがスプレッドシートを読み込みすぎないようにするトークン効率の高いデフォルト設定
• 後付けではなく、第一級の機能としての検証
• スプレッドシートを扱うエージェントが繰り返し苦労する一般的な変更処理に対応するワークフローヘルパー

トークン効率の高いワークフローの参考：

推奨される手順：

1. ブックとシートを検出する
2. 領域やテーブルのような構造を検出する
3. 必要な領域またはセルだけを確認する
4. ドライランまたはセッションへのステージングを使って変更する
5. 必要に応じて再計算する
6. 検証の証跡を確認し、グループ化された差分をレビューする

---

開発

# Build everything
cargo build --release

# Run formatting, lint, and tests
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

MCP のローカルでの反復開発：

WORKSPACE_ROOT=/path/to/workbooks ./scripts/local-docker-mcp.sh

または、MCP クライアントからローカルバイナリを直接指定できます：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "./target/release/agent-spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

---

さらに読む

• CLI パッケージの README： npm/agent-spreadsheet
• コアクレートの README： crates/agent-spreadsheet
• MCP クレートの README： crates/agent-spreadsheet-mcp
• JS SDK の README： npm/agent-spreadsheet-sdk
• WASM ラッパーの README： crates/agent-spreadsheet-wasm
• パッケージングとバージョン管理に関するメモ： docs/PACKAGING.md
• ヒューリスティクスと領域検出： docs/HEURISTICS.md
• 再計算のアーキテクチャ： docs/RECALC.md

---

ライセンス

Apache-2.0