formulon-mcp

@libraz/formulon-mcp は Formulon 用のローカル MCP サーバーです。AI エージェントが .xlsx と .xlsb のワークブックを開き、セルを読み書きし、数式を再計算し、プレビュー画像を描画して保存するまでを、Excel なしで実行できます。Formulon エンジンはサーバープロセス内で WASM として動き、編集内容は保存ツールで書き出すまでメモリ上にだけ存在します。

テンプレートへの入力、レポートの書式設定、計算シートの確認、表の集計など、ワークブック自体を変更する作業に使います。セットアップは npx -y @libraz/formulon-mcp init を実行し、インストールの手順に従ってください。

MCP、stdio、セッション

MCP（Model Context Protocol）は、Claude Code などの AI クライアントが外部ツールを呼び出すためのプロトコルです。stdio 接続では、クライアントが formulon-mcp を子プロセスとして起動し、stdin と stdout でメッセージをやり取りします。サーバーはネットワークポートを開きません。セッションは、サーバーのメモリ上に開いた 1 つのワークブックで、sessionId で指定します。サーバーが停止するとセッションは消えます。プロセスがアクセスできる範囲はセキュリティモデルを参照してください。

ガイドを選ぶ

ガイド	用途
インストール	Claude Code、Codex CLI、Claude Desktop などの MCP クライアントにサーバーを登録する
ワークフロー	開く、調べる、変更する、再計算する、プレビューする、保存する、閉じるまでの流れ。コメント、リンク、入力規則。セッション状態、変更あり（dirty）フラグ、損失情報、エラー
作成	ブロックから請求書、フォーム、レポートなどを作り、名前付き範囲を調整する
レイアウトとプレビュー	参照レイアウトの再現、画像と図形の挿入、寸法・シートビュー・印刷設定、PNG または SVG プレビューの確認
数式監査	繰り返し計算範囲の数式抜け、定数、外れ値、数式エラーの確認
テーブルとピボット	範囲からネイティブのワークシートテーブル（Table）とピボットテーブル（PivotTable）を作る
条件付き書式と入力規則	値や数式でセルを強調し、ドロップダウンや入力制限を付け、一致するセルを確かめる
高度な API	インストール済みの Workbook API を調べてから許可リスト内の低レベル呼び出しを行う
ツールリファレンス	登録済みツールの入力、既定値、上限、応答の形を確認する
セキュリティモデル	セッション分離、パス処理、低レベル API の許可リストを確認する

典型的な依頼

エージェントへのプロンプトには、入力ワークブック、変更内容、出力パスを指定します。例:

input.xlsx を開き、Summary!B2 の請求月を変更し、再計算して Summary!A1:H24 を確認用に描画し、編集結果を out/next-month.xlsx に保存してください。元ファイルは変更しないでください。

通常は次の経路を使います。

1. formulon_open_workbook でセッションを開きます。
2. シートを調べ、対象範囲を読み取ります。
3. formulon_set_cells または formulon_set_range で範囲を変更します。
4. 現在の数式結果が必要な時点で再計算します。
5. レイアウトを確認するときは formulon_preview_range を呼び出します。
6. outputPath を明示して保存し、セッションを閉じます。

次の作業にも対応します。

作業	最初に読むガイド
数式と書式を保ったまま、毎月のテンプレートを埋める	ワークフロー
テンプレートに確認用コメントやリンクを追加する	ワークフロー
しきい値を超えた金額を強調し、ステータスのドロップダウンを付ける	条件付き書式と入力規則
明細、税、合計から請求書を新規作成する	作成
スクリーンショットからフォームを再現し、保存前に改ページを確認する	レイアウトとプレビュー
計算表の数式抜けや不一致を確認する	数式監査
データ範囲をネイティブテーブル（Table）にして地域別に集計する	テーブルとピボット
専用ツールにないエンジンメソッドを使う	高度な API

対象となるファイルと処理

.xlsx と .xlsb を読み込めます。入力パスを指定しない場合はワークブックを作ります。シート名を含む新規ワークブックの既定値は、選んだ Excel プロファイルに従います。既定のプロファイルでは Sheet1 を作ります。計算とファイル解析は @libraz/formulon に委譲し、MCP サーバーはそのパッケージを WASM として読み込みます。このドキュメントはサーバー 0.11.0 を対象としています。インストール済みのサーバーとエンジンのバージョンは formulon_version で確認してください。

シートは 0 始まりの番号または完全一致するシート名で指定します。数値の row と col は 0 始まりです。Summary!B2 のような A1 参照は高レベルのセルツールで使えます。範囲読み取りとプレビューの A1 参照は、1 シート内の矩形範囲に限定されます。列全体、行全体、3-D 範囲は MCP の A1 パーサーで拒否されます。ただしスタイル適用（formulon_style_range と formulon_apply_layout の style 操作）は列全体と行全体を受け付けます。

通常の作業には高レベルツールを使い、インストール済み Workbook API が必要な場合は高度な経路を使います。高レベル呼び出しは入力を検証し、用途に合わせた JSON を返し、セッションの状態を管理します。formulon_workbook_call は明示的な許可リストに限定されるため、先に formulon_workbook_api でインストール済みのシグネチャと宣言を取得します。

ファイルと保存

パスは MCP サーバープロセスの作業ディレクトリから解決されます。保存では常に outputPath を明示し、拡張子を選びます。

• .xlsx は、作成したテーブル、ピボットテーブル、コメント、印刷設定などを保持したい場合に適しています。
• .xlsb はバイナリ形式を選びます。応答の losses に延期、格下げ、削除された機能が示されます。
• 保存応答の bytes はファイル内容ではなくバイト数です。

ファイルを開いたときに読み取れなかった部分があると、session.loadLosses に読み込み診断が入ります。保存時に保持できなかった内容は losses に入ります。ラウンドトリップが無損失だと判断する前に、両方を確認してください。損失がある保存後はセッションが変更あり（dirty）のままになります。

境界

• サーバーはツールのエンドポイントです。対話的なスプレッドシート UI には formulon-cell を使います。
• 任意の JavaScript や任意の Workbook メソッドは実行しません。低レベル呼び出しは許可リスト内に限られます。
• 変更が成功しても、ワークブックの業務ルールが正しいとは限りません。数式監査は確認候補を返しますが、数式の修復や計算の正しさの証明は行いません。
• プレビューはサーバーによる近似描画です。寸法、数式、フォント、改ページ、警告を返しますが、Excel と異なるフォントや未対応機能の表示差が生じる場合があります。

セッションの契約は ワークフロー で確認し、正確なフィールドや応答形が必要なときは ツールリファレンス を参照してください。