高度な Workbook API

Name: Formulon
Author: libraz

専用の MCP ツールで一般的なワークブック操作を行えます。サーバーは @libraz/formulon に ^0.18.0 の依存範囲を指定しています。実際に読み込まれたエンジンのバージョンは、各カタログ応答で確認してください。インストール済み Formulon の Workbook クラスに専用ツールがない機能は、formulon_workbook_api と formulon_workbook_call で扱えます。API カタログはサーバーが実際に読み込んだパッケージから作られ、シグネチャ、ドキュメント、読み書き区分、参照する TypeScript 宣言を含みます。先にメソッドを調べ、インストール済みのシグネチャに合わせて呼び出してください。

関数検索と Excel プロファイル

関数名、メタデータ、ロケール変換には formulon_function_lookup を使います。operation は names、metadata、localize、canonicalize、localizeFormula、canonicalizeFormula、localeFacts のいずれかです。profile は win-365-de_DE のような Excel プロファイルの ID で、変換先を決めます。省略するとセッションのプロファイルを使います。metadata はロケールに依存しません。names は保存用の関数名を列挙します。

操作	入力	結果
`localize`、`canonicalize`	`name`	関数名 1 件を、プロファイルの表記へ、またはプロファイルの表記から変換します。Excel が関数名をローカライズするのは de_DE、fr_FR、es_ES、es_MX、pt_BR、ru_RU、it_IT、nl_NL です。他のプロファイルでは英語名のままです。
`localizeFormula`、`canonicalizeFormula`	`formula`	数式全体を、保存用の英語形式とプロファイルの表記の間で書き換えます。区切り文字や小数点も含みます。
`localeFacts`	なし	区切り文字、真偽値の名前、日付の順序、通貨の配置、ローカライズされたエラー名、`measured`、`collationMeasured` を返します。

json

{
  "name": "formulon_function_lookup",
  "arguments": {
    "sessionId": "work",
    "operation": "localizeFormula",
    "formula": "=SUM(A1,1.5)",
    "profile": "win-365-de_DE"
  }
}

de_DE では =SUM(A1,1.5) が =SUMME(A1;1,5) になり、canonicalizeFormula で元に戻ります。

検索、説明、呼び出し

メソッド名、シグネチャ、ソースドキュメントを検索します。

json

{
  "name": "formulon_workbook_api",
  "arguments": {
    "operation": "search",
    "query": "pivotLayout",
    "limit": 20,
    "offset": 0
  }
}

検索結果には読み込んだエンジンの version、操作名、total、count、truncated、methods が入ります。limit の既定値は 20、上限は 100 です。offset は 0 始まりです。query はメソッド名、シグネチャ、ドキュメントへの大文字小文字を区別しない部分一致です。

describe で対象メソッドの説明を取得し、位置引数を組み立てます。

json

{
  "name": "formulon_workbook_api",
  "arguments": {
    "operation": "describe",
    "method": "createTable"
  }
}

応答には 1 つのメソッドと declarations が入ります。宣言には参照レコードと列挙型のソース説明および TypeScript 宣言が含まれます。宣言数、参照深度、文字数に上限があり、結果が途中で切れた場合は declarationsTruncated と truncation で示します。メソッドの引数順と列挙値は、この応答を基準にしてください。

先に formulon_open_workbook に { "sessionId": "work" } を渡してセッションを開きます。そのセッションに対して、位置引数の JSON 配列で呼び出します。

json

{
  "name": "formulon_workbook_call",
  "arguments": {
    "sessionId": "work",
    "method": "addMerge",
    "args": [
      0,
      { "firstRow": 0, "firstCol": 0, "lastRow": 0, "lastCol": 3 }
    ]
  }
}

args の既定値は空配列です。MCP ツールは引数順を変換せず、既定値を補わず、オブジェクトをレコードへ変換しません。サーバーの許可リストにないメソッド、または読み込んだワークブックで呼び出せないメソッドは呼び出し時に失敗します。引数を作る前にライブカタログを調べてください。

実用的なプロンプトは次のようになります。

インストール済み Workbook API から現在のシート表示を読むメソッドを探してください。説明を取得し、シート番号 0 に対して呼び出し、ワークブックは変更しないで結果を返してください。

エージェントは getSheetView を検索し、説明を取得してから発見した引数で呼び出します。TypeScript のレコードや列挙値が変わっても、古い手書き引数を送らずに済みます。

許可されるメソッド

サーバーの許可リストは明示的です。次のグループを含みます。

シートの作成、削除、名前変更、移動、値、数式、セルメタデータ、定義名、行列の挿入、ワークシート寸法
計算、部分再計算、並列再計算、計算モード、反復計算、数式評価、依存関係グラフ、スピル情報（動的配列の展開範囲）、関数名とメタデータ
ワークブック時計の固定、Excel プロファイル、読み込み診断、ページネーション、ページ設定、余白、印刷オプション、ヘッダー・フッター、印刷範囲、印刷タイトル、手動改ページ
ワークシートテーブル、AutoFilter、ピボットキャッシュ、ピボットテーブル、フィールド軸と順序、データフィールド、フィルター、日付グループ、ネイティブピボットテーブルのレイアウト
シート表示、保護、グリッド線、表示フラグ
フォント、塗りつぶし、罫線、表示形式、セルスタイル、差分書式、セル XF、範囲 XF。行・列スタイル（setColumnStyle、clearColumnStyle、setRowStyle、clearRowStyle）、属性だけの範囲書式（rangeStyleBases、remapRangeStyle）、clearCellXfIndex、clearColumnWidth を含みます
テーマのスクリプトフォントとリセット（setThemeScriptFont、resetTheme）、画像とグラフの配置と重なり順（setDrawingAnchor、setDrawingZOrder）
グラフ：読み取り専用の getChart、getChartData、previewChartData と、作成・編集用の insertChart、setChartType、setChartTitle、setChartLegend、setChartAxis、setChartDisplay、setChartSeries、setChartPoint、setChartPlot、setChartFilter、addChartSeries、removeChartSeries、setChartSource
ロケールと照合順序の取得（localizeFormula、canonicalizeFormula、localeFacts、compareText、collationClasses）。読み取り専用で、セッションを変更ありにしません。照合クラス ID は単純な JSON 配列で返ります
結合、コメント（setCommentVisible を含む）、ハイパーリンク、入力規則、条件付き書式、ふりがな、外部リンク
描画の図形（listShapes、insertShape、updateShape、removeShape）、スライサー（listSlicers、addSlicer、updateSlicer、removeSlicer）、What-If データテーブル（getDataTable、addDataTable、removeDataTable、recalcDataTables）、スパークライングループ（listSparklineGroups、addSparklineGroup、updateSparklineGroup、setSparklineGroupSparklines、removeSparklineGroup）
ブックの保護と保護された範囲（getWorkbookProtection、setWorkbookProtection、getProtectedRanges、addProtectedRange、updateProtectedRange、removeProtectedRange）
テーブルスタイル（tableStyleCount、getTableStyle、getTableStyleDefaults、setTableStyle、removeTableStyle、setTableStyleDefaults、setTableColumnTotals）とピボットテーブルの読み戻し（pivotCacheId、pivotName、pivotGetGrandTotals、pivotGetStyleInfo、pivotFieldAt、pivotFieldItemCount、pivotFieldItemAt、pivotDataFieldAt、pivotRowFieldOrder、pivotColFieldOrder、pivotSetStyleInfo）
計算設定（fullPrecision、calcOnSave、refMode、date1904 とそれぞれの setter）、シート選択・分割・左上セル・アクティブシート（getSheetSelection、setSheetSelection、setSheetSplit、setSheetTopLeft、setSheetPaneTopLeft、activeSheet、setActiveSheet）、アウトラインの折りたたみ（setRowCollapsed、setColumnCollapsed）、定義名の属性（setDefinedNameAttrs）

疎なセル・結合範囲の取得（getCellsInRange、getMergesInRange）、A1 / R1C1 数式の取得、表示テキストと値の書式変換、ジオメトリと列幅モデル、テーマの色・フォント、有効なスタイル、シート・テーブルの型付き AutoFilter、入力規則の検査、スレッドコメントと人物、描画・画像の取得と削除（removeDrawing）も許可されています。呼び出す前に、正確なメソッドとレコードの項目を確認してください。フィルターの適用は行の表示状態を変え、依存する数式を再計算待ちにします。更新後の SUBTOTAL や AGGREGATE の値を読む前に formulon_recalc_session を呼んでください。

probeImage と insertImage はバイナリ入力を取るため、低レベルの JSON 呼び出しでは使えません。ファイルの挿入や画像バイトの取得には、画像操作の formulon_image_operation を使います。snapshotDrawing / restoreDrawing と snapshotRangeStyle / restoreRangeStyle も許可されません。不透明なバイト列を往復させるため、JSON の結果では長さだけになり、JSON の引数ではバイト列を渡せないからです。

これらのうち取得系（listShapes、getDataTable、date1904、pivotGetStyleInfo など）は読み取り専用に分類され、セッションを変更ありにしません。専用ツールがある操作はそちらを使ってください。formulon_shape_operation、formulon_sparkline_operation、formulon_data_table_operation は入力を検証し、A1 アドレスを解決しますが、生のメソッドは行いません。

save、saveAs、saveWithDiagnostics はセッション管理を迂回するため許可されません。保存は outputPath を明示した formulon_save_session を使います。delete、isValid、JavaScript コールバックを受け取る setIterativeProgress も JSON 呼び出しには適さないため許可されません。

応答エンベロープ

formulon_workbook_call は {session,method,result} を返します。次の例は応答全体ではなく、内側の result の内容です。エンジンの status フィールドを保持します。取得メソッドでは次の形を使います。

json

{
  "status": { "ok": true, "status": 0, "message": "", "context": "" },
  "value": 3
}

json

{
  "status": { "ok": true, "status": 0, "message": "", "context": "" },
  "items": [
    { "name": "Sheet1", "index": 0 }
  ]
}

status の後に続くフィールドは発見したメソッドに従います。数値や文字列の取得メソッドは value、一覧は items、pinnedNow、readDiagnostics、ピボットテーブルのレイアウトなどは固有フィールドを返します。ネイティブの値は {kind, value} またはエラーエンベロープになります。ok でない status は空の成功結果ではなく MCP エラーになります。

読み取り専用区分はサーバーが明示的に管理します。読み取り専用呼び出しは変更あり（dirty）の状態を変えません。それ以外の許可メソッドは、エラー報告前にネイティブ状態が変わる可能性があるため、呼び出し前にセッションを変更あり（dirty）にします。変更に失敗した場合はセッションを調べ、対象範囲を読み取ってください。

ワークブック時計を固定する

時刻依存の数式と相対期間のピボットテーブルフィルターを同じ瞬間で評価するには、[year, month, day, hour, minute, second] の 6 つの位置引数で時計を固定します。

json

{
  "name": "formulon_workbook_call",
  "arguments": {
    "sessionId": "work",
    "method": "setPinnedNow",
    "args": [2026, 10, 1, 9, 30, 0]
  }
}

以降の NOW()、TODAY()、相対期間フィルターの評価は固定時刻を参照します。setPinnedNow は既存の数式キャッシュを再計算しません。セルを読む前に formulon_recalc_session を呼んでください。固定を解除した後も、キャッシュをホスト時計に合わせるには再計算が必要です。pinnedNow で読み取り、clearPinnedNow でホスト時計へ戻します。

json

{
  "name": "formulon_workbook_call",
  "arguments": {
    "sessionId": "work",
    "method": "pinnedNow",
    "args": []
  }
}

json

{
  "name": "formulon_workbook_call",
  "arguments": {
    "sessionId": "work",
    "method": "clearPinnedNow",
    "args": []
  }
}

固定値はインメモリのモデルにだけ存在し、保存されません。別プロセスでも同じ瞬間を使う場合は、セッションを開いた後に再度設定してください。

再計算と WASM ランタイム

サーバーは Formulon の既定の単一スレッド WASM モジュールを読み込みます。recalcParallel は API 互換性のため許可されていますが、このランタイムでは直列に評価され、result.stats.workerThreadsStarted: 0 を返します。通常の再計算には専用の formulon_recalc_session を使い、発見したメソッドの結果やオプションが必要な場合だけ recalcParallel を使います。

json

{
  "name": "formulon_workbook_call",
  "arguments": {
    "sessionId": "work",
    "method": "recalcParallel",
    "args": [0]
  }
}

この呼び出しは、低レベルの変更系計算と同じくセッションを変更あり（dirty）にします。result.status はエンジン呼び出しの結果を示しますが、業務ルールの正しさは示しません。

低レベル API の注意点

PivotCache とワークシートのソース

低レベル API で作った PivotCache は、保存前に pivotCacheSetWorksheetSource でワークシートのソースへ接続してください。ソース宣言のないキャッシュは Excel の修復対象になる場合があります。formulon_create_pivot はこの手順と範囲検証を実行します。

ピボットテーブルのフィールド順

フィールドの軸を設定するだけでは、グループ化したフィールド順は設定されません。pivotFieldSetAxis を使う場合は pivotSetRowFieldOrder と pivotSetColFieldOrder も呼び出します。高レベルのピボットテーブルツールは両方を実行します。

ピボットテーブルの表示形式

低レベルのピボットフィールドとデータフィールドは、Excel の書式コードではなく 10 進数の numFmtId 文字列を受け取ります。カスタムコードは addNumFmt で登録し、返された ID を文字列で渡します。組み込み ID の "4" などを使える場合もあります。高レベルのピボットテーブルツールは書式コードを受け付けて ID を登録します。

印刷と表示の生の XML を扱う API

低レベル経路では、ページ設定 XML、シート表示フラグ、保護、ページネーションを扱えます。XML 断片や列挙値を渡す前に、正確な宣言を調べてください。一般的なレイアウトには formulon_print_settings、formulon_apply_layout、formulon_preview_range の型付き経路を使います。

高度な呼び出し後の保存

低レベル呼び出しはファイルを書き込みません。返された status と変更対象を確認してから、セッション API で明示的な保存先へ保存します。保存先の out ディレクトリは、先にホスト側で作成してください。保存ツールとプレビューツールは親ディレクトリを作成しません。

json

{
  "name": "formulon_save_session",
  "arguments": {
    "sessionId": "work",
    "outputPath": "out/advanced-result.xlsx"
  }
}

保存後は losses とセッションの dirty を確認してください。ネイティブテーブル、ピボットテーブル、印刷設定、コメントを保持する必要がある場合は .xlsx を使います。確認後はセッションを閉じます。

json

{
  "name": "formulon_close_workbook",
  "arguments": { "sessionId": "work" }
}

高レベルの全ツールはツールリファレンス、セッションの流れとエラーはワークフローを参照してください。

高度な Workbook API ​

関数検索と Excel プロファイル ​

検索、説明、呼び出し ​

許可されるメソッド ​

応答エンベロープ ​

ワークブック時計を固定する ​

再計算と WASM ランタイム ​

低レベル API の注意点 ​

PivotCache とワークシートのソース ​

ピボットテーブルのフィールド順 ​

ピボットテーブルの表示形式 ​

印刷と表示の生の XML を扱う API ​

高度な呼び出し後の保存 ​

高度な Workbook API

関数検索と Excel プロファイル

検索、説明、呼び出し

許可されるメソッド

応答エンベロープ

ワークブック時計を固定する

再計算と WASM ランタイム

低レベル API の注意点

PivotCache とワークシートのソース

ピボットテーブルのフィールド順

ピボットテーブルの表示形式

印刷と表示の生の XML を扱う API

高度な呼び出し後の保存