SheetForge MCP

Local-first Excel MCP server for AI agents that need structured reads, workbook introspection, and safer .xlsx mutation.

SheetForge MCP is an Excel MCP server for .xlsx automation over the Model Context Protocol. It is built for AI agents, MCP clients, and automation workflows that need more than raw cell access: compact structured reads, workbook-aware guidance, layout-aware inspection, and safer write paths with Python and openpyxl, without launching Microsoft Excel or LibreOffice.

If you are looking for an Excel MCP server for spreadsheet automation, workbook inspection, Excel report generation, dashboard authoring, or .xlsx editing from AI tools, SheetForge MCP is built for that workflow.

Instead of treating every sheet as a blind cell grid, SheetForge helps agents distinguish native Excel tables, worksheet-shaped datasets, layout-heavy dashboards, and chart sheets, then choose the right read or mutation path for each workbook task.

Package name: sheetforge-mcp CLI command: sheetforge-mcp Published package release: 0.15.0 Repository docs track the current main-branch tool surface, which currently exposes 83 MCP tools. Version 0.15.0 adds opt-in preserving XLSX saves for literal cell edits in a restricted workbook profile. Targeted XLSX fidelity checks still guard direct and ChangeSet-backed writes. Workbook Contracts v1 is included in 0.14.0: explicit bindings and full bounded data checks can guard Recipe preview/commit, with logical-field, file-path and worksheet-versus-table recovery guidance. Verified Recipes v1 is included in 0.11.0: reusable native-table reports with explicit checks and verified preview/commit. Verified Explanations v1 is included in 0.12.0: read-only, independently reconciled changes between recomputed recipe results. Verified Rebase and Verified Scenarios v1 are included in 0.13.0: intent-preserving keyed edits and outcome-checked alternatives with verified commits.

Why SheetForge

• reusable workbook contracts via inspect_workbook_contract and optional Recipe enforcement: separate declared meanings from checked key/type/value rules, resolve only approved exact headers, block ambiguous bindings, and guide agents through logical-field errors without weakening the contract

• outcome-checked alternatives via evaluate_workbook_scenarios: compare explicit keyed changes against exact overall/group metric bounds, then commit one selected outcome with post-save recomputation and rollback

• intent-preserving table edits via apply_table_patch: rebind keyed updates against a pinned base, reject changed premises and conflicting writes, and commit a fresh verified preview while keeping unrelated current values

• agent-friendly reads via suggest_read_strategy, describe_dataset, query_table, and aggregate_table

• safer cell and multi-step edits: write_data_to_excel checks a staged save for targeted XLSX losses; apply_workbook_changeset adds value/table/layout assertions, a structural diff, and commit against the exact previewed source bytes

• reusable report recipes via run_workbook_recipe: filter and aggregate a native table, check the result, and write it through a verified ChangeSet without passing intermediate rows through the model

• explainable report changes via explain_recipe_delta: recompute the same recipe on two source versions, compare by unique keys, and reconcile added/removed/updated contributions without modifying either workbook

• safer workbook creation and baselines: create_workbook refuses to overwrite an existing .xlsx, while create_workbook_snapshot creates a verified non-overwriting copy for before/after validation

• serialized workbook mutation: same-host writers lock each workbook before loading it, then keep the lock through atomic replace and reopen verification so concurrent agents do not silently overwrite one another

• smarter worksheet boundaries with bounded strict, default, and extended read presets plus compact metadata for any trailing blocks that were intentionally left out

• workbook and layout awareness via profile_workbook, describe_sheet_layout, list_tables, list_charts, and analyze_range_impact

• safer local mutation through dry_run, compact write responses, guarded native-table append/upsert flows, and workbook diff/audit/repair loops

• local-first performance and privacy with openpyxl, no desktop Excel dependency, and no cloud-auth requirement

Related MCP server: fcp-sheets

Excel MCP Server Features

• workbook creation and metadata

• worksheet creation, renaming, copying, deletion, and visibility

• structured reads, compact table reads, declarative table queries, grouped aggregates, and cell search

• row, column, and range mutations

• formulas and validation checks

• formatting, freezes, autofilters, merges, and conditional formatting

• native Excel tables, charts, and pivot summaries

• stdio, streamable-http, and deprecated sse transports

Common Use Cases

• AI agents that need safe, structured Excel workbook access through MCP

• spreadsheet automation workflows that read and update .xlsx reports

• Excel dashboard generation with formatting, tables, charts, freeze panes, and print setup

• workbook QA and inspection flows that need metadata, named ranges, tables, charts, and protection state

• data extraction from native Excel tables or worksheet-shaped datasets without hand-written openpyxl scripts

Requirements

• Python 3.10+

• .xlsx workbooks

• either uvx or a local package install

Quick Start

Install and run directly from PyPI with uvx, or install the package locally in your Python environment.

Stdio

Use stdio when the MCP client starts the server locally.

uvx sheetforge-mcp stdio

{
  "mcpServers": {
    "excel": {
      "command": "uvx",
      "args": ["sheetforge-mcp", "stdio"]
    }
  }
}

Streamable HTTP

Use streamable-http when you want a long-running local server process.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp streamable-http

Default endpoint:

http://127.0.0.1:8017/mcp

Example client config:

{
  "mcpServers": {
    "excel": {
      "url": "http://127.0.0.1:8017/mcp"
    }
  }
}

Remote binding is an explicit opt-in because the HTTP transports do not provide built-in authentication:

FASTMCP_HOST=0.0.0.0 \
SHEETFORGE_ALLOW_REMOTE=true \
EXCEL_FILES_PATH=/path/to/excel-files \
uvx sheetforge-mcp streamable-http

Only expose a remote listener behind an authenticated and access-controlled network boundary.

SSE

SSE is kept for compatibility, but new integrations should prefer streamable-http.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp sse

Default endpoint:

http://127.0.0.1:8017/sse

File Path Rules

• Paths refer to the server filesystem, not the client's cwd. Reuse supplied paths; never invent an absolute prefix for a relative name.

• In stdio mode, filepath values must be absolute paths.

• In streamable-http and sse mode, relative paths are resolved under EXCEL_FILES_PATH.

• In streamable-http and sse mode, absolute paths are accepted only when they remain inside EXCEL_FILES_PATH; parent traversal and symlink escapes are rejected.

• In streamable-http and sse mode, the server creates EXCEL_FILES_PATH automatically if it does not exist.

Path-policy errors include a stable code and safe next step. Retry the original user-supplied root-relative path on a rooted server, or ask for the intended absolute path in normal stdio. No automatic basename fallback or relocation occurs. See path guidance and error recovery.

Environment Variables

Tooling Overview

Worksheet tabs and native Excel tables have separate names. For a named source, use list_tables to verify its containing tab, then read_excel_table; a missing name in the worksheet list does not prove the table is absent. See source selection and error recovery.

The server currently registers 83 MCP tools across these groups:

• workbook overview: create_workbook, create_worksheet, create_workbook_snapshot, get_workbook_metadata, profile_workbook, describe_sheet_layout, audit_workbook, plan_workbook_repairs, apply_workbook_repairs, apply_workbook_changeset, run_workbook_recipe, explain_recipe_delta, diff_workbooks, analyze_range_impact, explain_formula_cell, detect_circular_dependencies, create_named_range, inspect_named_range, list_named_ranges, delete_named_range, list_all_sheets, list_tables

• data access: suggest_read_strategy, describe_dataset, query_table, aggregate_table, bulk_aggregate_workbooks, bulk_filter_workbooks, union_tables, cross_workbook_lookup, quick_read, read_excel_table, read_data_from_excel, read_excel_as_table, search_in_sheet, write_data_to_excel, append_table_rows, append_excel_table_rows, upsert_excel_table_rows, update_rows_by_key

• worksheet and range changes: copy_worksheet, delete_worksheet, rename_worksheet, set_worksheet_visibility, get_worksheet_protection, set_worksheet_protection, copy_range, delete_range, insert_rows, insert_columns, delete_sheet_rows, delete_sheet_columns

• formatting and layout: format_range, format_ranges, read_range_formatting, freeze_panes, set_autofilter, set_print_area, set_print_titles, set_column_widths, autofit_columns, set_row_heights, merge_cells, unmerge_cells, get_merged_cells

• formulas and validation: apply_formula, validate_formula_syntax, inspect_formula, validate_excel_range, get_data_validation_info, inspect_data_validation_rules, remove_data_validation_rules, inspect_conditional_format_rules, remove_conditional_format_rules

• analysis and structure: create_table, list_charts, find_free_canvas, create_chart, create_chart_from_series, create_pivot_table

• guarded table patches: apply_table_patch

• guarded alternatives: evaluate_workbook_scenarios

• workbook contracts: inspect_workbook_contract and run_workbook_recipe(..., workbook_contract=...)

For explicit reusable field definitions and mandatory source checks before report generation, see the Workbook Contracts guide and net-sales contract. Declared business meanings are not machine-verified facts. V1 integrates Recipes only; it does not silently enforce contracts on other tools.

For comparing proposed edits before choosing one, see the Verified Scenarios guide and budget example. Scenarios verify explicit sum/count bounds, not forecasts or the business correctness of a decision.

For native-table edits prepared against an earlier snapshot, see apply_table_patch and the Verified Rebase guide. This is separate from unconditional key-based upserts: declared read dependencies and old target values are checked before compiling a fresh ChangeSet.

For chart authoring, prefer create_chart as the primary entry point:

• use data_range for the simple contiguous-data path

• use explicit series plus optional categories_range for non-contiguous or hand-authored charts

• use top-level width and height to control chart size in centimeters; defaults are 15 x 7.5

• use placement when you want SheetForge to position the chart relative to worksheet content, a source range, or a named table instead of guessing target_cell manually

• use placement={"relative_to": "free_canvas"} when a busy dashboard needs the first non-overlapping chart slot instead of a simple right/below placement rule

• keep create_chart_from_series for backward compatibility or existing prompts that already rely on it

The most agent-friendly read tools are:

• suggest_read_strategy: recommends the best next read tool for a workbook target, including whether SheetForge should treat it as a native Excel table, a clean worksheet dataset, a layout-heavy dashboard sheet, or a chart sheet

• describe_dataset: samples a worksheet or native Excel table and returns headers, schema hints, key-candidate guesses, structural signals, guarded worksheet-boundary metadata, and a recommended follow-up read path

• query_table: filters, projects, sorts, and limits worksheet-shaped data or native Excel tables with a declarative JSON query instead of ad hoc cell loops

• aggregate_table: computes grouped metrics such as count, sum, avg, min, and max over worksheet-shaped data or native Excel tables

• bulk_aggregate_workbooks: computes the same grouped metrics across many workbook files in one call, with explicit schema handling via strict, intersect, or union

• bulk_filter_workbooks: returns matching rows across many workbook files with optional source provenance columns, so recurring cross-file QA and reporting checks no longer need one-tool-call-per-file loops

• union_tables: combines comparable worksheet or native-table rows across many workbook files, with optional deduplication keys and explicit schema handling for workbook collections that drift over time

• cross_workbook_lookup: enriches one workbook dataset from one or more lookup workbooks with left-join style matching, optional duplicate-match handling, and compact per-row provenance for matched lookup rows

• profile_workbook: one-call inventory for sheets, tables, charts, named ranges, and key layout/protection state, including chart occupied_range for grid-anchored worksheet charts

• describe_sheet_layout: worksheet-level structural summary for safe dashboard edits, including freeze panes, print settings, merges, chart anchors, table metadata, conditional-format and validation counts, custom row/column sizing, and a small free-canvas preview

• audit_workbook: workbook-level audit for high-signal problems such as broken #REF! formulas, error cells, hidden sheets, header-quality issues, layout-heavy sheets, and named ranges that reference missing sheets

• plan_workbook_repairs: converts workbook audit findings into prioritized next steps, including suggested SheetForge tool calls for inspection, safe dry runs, and repair workflows

• apply_workbook_repairs: dry-runs or applies the safe repair subset from those plans, including broken named ranges, broken validation rules, broken conditional formats, and optional hidden-sheet reveals

• apply_workbook_changeset: previews a bounded multi-tool report mutation on an isolated candidate, evaluates explicit postconditions, and commits it with exact-file stale-write protection plus optional verified snapshot and rollback

• run_workbook_recipe: executes a versioned JSON recipe over one native table, checks unique keys, row counts or sum reconciliation, probes column/row-order invariance, and writes a reserved rectangle in the same workbook through ChangeSet preview/commit. See the Verified Recipes guide and example recipe.

• explain_recipe_delta: independently reconciles changes in recomputed sum/count recipe results across two source versions by unique keys. Includes group drilldown, exact decimal evidence and explicit sample remainders. It does not validate saved report cells or infer business causes. See Verified Explanations.

• diff_workbooks: compares two workbook files and reports structural changes plus sampled cell-value diffs, which is useful for before/after verification in agent workflows

• create_workbook_snapshot: creates the verified, non-overwriting baseline that makes diff_workbooks usable without an external copy script

• analyze_range_impact: preflight blast-radius check for a worksheet range, including overlaps with tables, chart footprints, merged cells, named ranges, data validations, conditional formats, autofilters, print areas, formula cells inside the range, and formulas or rule expressions elsewhere that depend on it directly or transitively, through named ranges, or through structured table references such as Table1[Sales]

• explain_formula_cell: resolves a formula cell's direct references, shows upstream formula-chain cells, returns a compact formula_chain summary with depth layers and sampled paths, and reports downstream dependents so agents can debug workbook logic without manual tracing

• detect_circular_dependencies: scans workbook formula graphs, including named-range-driven edges, and reports self-references plus multi-cell circular dependency groups before they surprise downstream automation

• create_named_range: creates workbook-level or sheet-scoped named ranges with dry_run and replace support, so agents can promote important workbook regions into stable references without dropping to ad hoc Python

• inspect_formula: inspects a formula string without workbook context, listing functions, reference token types, volatile functions, and risky functions such as INDIRECT

• inspect_named_range: inspects one defined name, including its scope, destinations, and whether it points at missing sheets or broken references

• quick_read: single-call compact table read that auto-selects the first sheet when needed, with guarded strict / default / extended boundaries, start_row pagination, and start_col / end_col column windowing for large sheets

• read_excel_table: read a native Excel table by table_name without guessing worksheet bounds, now with start_row pagination and optional start_col / end_col table column windowing

• list_all_sheets: quick workbook inventory with sheet sizes, emptiness flags, and sheet_type for worksheets versus chart sheets

• read_excel_as_table: compact headers + rows output for structured datasets, with guarded boundary presets, compact=True for the smallest payload, start_row for page-like reads, and start_col / end_col for narrower column slices

• read_data_from_excel: cell-address-aware range reader that supports max_rows and max_cols windowing for large non-tabular ranges, values_only=True for smaller 2D payloads, and cursor-based continuations for multi-step 2D traversal

• read_range_formatting: compact formatting readback for a worksheet range, grouped by distinct style signatures instead of noisy per-cell dumps, with merged-range and conditional-format overlap summaries

• search_in_sheet: exact or partial value search across instantiated worksheet cells, so distant style-only cells do not force a scan of the entire rectangular used range

Workbook inventory tools such as list_all_sheets, profile_workbook, and list_charts surface both worksheets and chart sheets. Grid-oriented tools such as quick_read, read_excel_table, create_table, formatting, formulas, and validation require a real worksheet and return a clear chartsheet error if you target the wrong sheet type.

The most agent-friendly write helpers for structured data are:

• upsert_excel_table_rows: update matching rows in a native Excel table and append missing keys in one call Note: totals-row tables are update-only for now; append attempts are rejected rather than shifting unrelated rows.

• append_excel_table_rows: append rows to a native Excel table when you want the table ref to grow with the new records

• append_table_rows: append header-aware rows to worksheet-shaped data when you do not have a native Excel table

• update_rows_by_key: update worksheet-shaped data by a named key column without appending missing keys

For the compact table readers (quick_read, read_excel_as_table, read_excel_table):

• row_mode="arrays" keeps the smallest headers + rows shape

• row_mode="objects" returns records keyed by normalized field names such as first_name

• normalized field names are ASCII-safe transliterations, so headers like Näyttökerrat become nayttokerrat

• infer_schema=True adds lightweight schema hints inferred from the returned rows

• start_col / end_col let you slice wide worksheets or native Excel tables down to just the columns you need before pagination or schema inference

• truncated pages now include next_start_row, which you can pass back to the same tool for the next page

• non-tabular range reads can also return continuations.down and continuations.right cursor tokens so agents can continue large 2D windows without recomputing coordinates

• suggest_read_strategy helps agents choose between table-aware, worksheet-aware, range-aware, and workbook-orientation reads before they spend context on the wrong path

• describe_dataset provides a lighter-weight dataset summary than a full read, including sample rows, header quality, key candidates, and recommended next tool

• describe_dataset, quick_read, read_excel_as_table, and read_excel_table now also return structure_token, content_token, and snapshot_metadata, so agents can carry read-time identity forward into safer optimistic-concurrency writes

• worksheet-shaped compact readers and row-mutation helpers favor the first contiguous data block after the header, so sparse footer notes or distant outlier rows do not silently stretch total_rows, append targets, or key-based update scans

• worksheet reads can opt into read_boundary_mode="strict" (0 blank rows), "default" (5), or "extended" (100); the bounded presets deliberately avoid an unlimited raw gap parameter

• describe_dataset, quick_read, and read_excel_as_table surface a read_boundary object with the effective tolerance, data end, ignored row count, and compact trailing-block locations

• non-default boundary views are read-only diagnostics and return write_precondition_compatible=false; reread with the default mode before carrying a structure token into a write

• query_table is the lightest way to pull just the matching rows and columns you need from a worksheet dataset or native Excel table

• query_table and bulk_filter_workbooks accept ne as a shorthand for neq, and membership filters can use either values or the shorter value list form

• aggregate_table lets agents compute grouped summaries directly in SheetForge instead of over-reading the full dataset into context first

• bulk_aggregate_workbooks extends that pattern across many workbook files when a recurring reporting workflow would otherwise need ad hoc Python or repeated per-file tool calls

• aggregate metrics accept both the canonical {"op": "sum", "field": "Sales", "as": "total_sales"} shape and the more guessable alias form {"agg": "sum", "column": "Sales", "as": "total_sales"}

• bulk_filter_workbooks does the same for row-level inspection, while keeping workbook provenance visible by default

• union_tables is the fastest way to normalize many comparable workbook datasets into one combined tabular payload before downstream QA, export, or further aggregation

• cross_workbook_lookup is the fastest way to enrich one workbook from another without writing an ad hoc merge script, especially for master-data lookups, status enrichment, and cross-file QA workflows

• append_excel_table_rows is the right append path for native Excel tables when you do not need key-based upsert behavior

• append_table_rows now refuses to write directly under an adjacent native Excel table and points you at append_excel_table_rows instead of silently leaving the table range stale

• token-aware structured writes can pass expected_structure_token to abort on structural drift; append-style writes additionally require allow_structure_change=True, and successful writes report both previous and new structure/content tokens

• rename_worksheet now updates formula cells as well as chart references and named ranges, and it also renames the default sibling pivot sheet (Data_pivot -> Revenue_pivot) when that move is conflict-free

• copy_worksheet preserves native tables with workbook-unique copied names, data validations, conditional formatting, freeze panes, autofilters, print settings, protection, charts with their exact anchor geometry, and sheet-scoped names; copied self-references and structured table references are rewritten to the new sheet

• formatting color inputs accept RRGGBB, #RRGGBB, AARRGGBB, or #AARRGGBB, so prompts do not need to strip CSS-style # prefixes first

• audit_workbook is the fastest workbook-wide preflight when you need to know whether a spreadsheet is safe and predictable enough for autonomous editing

• audit_workbook now treats dominant native-table sheets more honestly when nearby dashboard/layout artifacts extend the used range, so unrelated merged/chart areas do not create false blank-header risk on an otherwise clean table

• plan_workbook_repairs is the fastest way to turn those audit findings into an actual action queue instead of manually deciding the next tool call for every problem

• apply_workbook_repairs lets agents preview or apply the safe subset of those repairs without having to orchestrate each broken workbook artifact manually

• diff_workbooks is the quickest before/after QA pass when an agent has touched workbook structure and wants proof of what actually changed

Recommended Agent Workflows

1. Unfamiliar workbook -> verified multi-step mutation Start with profile_workbook (or list_all_sheets for the lightest inventory), inspect layout-heavy tabs with describe_sheet_layout, and run analyze_range_impact. Put supported report-building edits and explicit postconditions into apply_workbook_changeset(mode="preview"). Review package_fidelity; only if ready_to_commit=true should you repeat the same plan with mode="commit", expected_workbook_sha256, and changeset_token from the preview. See XLSX fidelity checks and the preserving save mode for restricted literal cell edits.

2. Workbook repair loop Use audit_workbook to find high-signal issues, plan_workbook_repairs to turn them into an action queue, apply_workbook_repairs(..., dry_run=True) to preview the safe subset, then rerun audit_workbook after applying repairs to confirm the workbook is back to a low-risk state.

3. Multi-workbook reporting Use bulk_aggregate_workbooks, bulk_filter_workbooks, union_tables, or cross_workbook_lookup to build the reporting dataset first, then write the summarized rows into a fresh workbook tab and finish the presentation layer with format_ranges, find_free_canvas, create_chart, and autofit_columns.

See TOOLS.md for the full reference. Release notes live in CHANGELOG.md.

Response Format

Every tool now returns a JSON envelope with a consistent top-level shape:

{
  "ok": true,
  "operation": "read_excel_as_table",
  "message": "read_excel_as_table completed",
  "data": {}
}

Error responses follow the same contract:

{
  "ok": false,
  "operation": "write_data_to_excel",
  "error": {
    "type": "DataError",
    "message": "No data provided to write"
  }
}

For destructive tools that support preview mode, the envelope may also include dry_run and changes. Committed write operations now default to compact summaries; pass include_changes=True when you want per-cell, per-range, or per-operation detail.

Development

Install dependencies:

uv sync --extra dev

Run tests:

uv run --extra dev pytest -q

Run lint checks:

uv run --extra dev ruff check src tests

Run the package locally:

uv run sheetforge-mcp stdio

Build distributions locally:

uv build

Release Flow

• Update pyproject.toml, manifest.json, and the tracked .mcpb bundle together for each release.

• Keep the tracked bundle filename in sync with the package version, for example sheetforge-mcp-<version>.mcpb.

• Every distribution-building workflow verifies the wheel, source distribution, and tracked MCPB bundle against shared public-artifact allowlists before release or publication.

• GitHub releases run a build verification workflow only.

• PyPI publishing is a separate manual workflow, so releases do not create a failing deployment before Trusted Publisher is configured for the package.

Repository Layout

• src/excel_mcp/server.py: MCP server, transport setup, and tool registration

• src/excel_mcp/workbook.py: workbook lifecycle helpers and workbook metadata

• src/excel_mcp/changeset.py: verified multi-operation preview/commit transactions and assertions

• src/excel_mcp/recipes.py: bounded native-table report recipes, checks, lineage samples, and ChangeSet compilation

• src/excel_mcp/explanations.py: read-only keyed recipe deltas with independent arithmetic/filter checks and bounded evidence

• src/excel_mcp/data.py: read, write, table, and search helpers

• src/excel_mcp/sheet.py: worksheet and range mutations

• tests/: regression tests covering data, layout, charts, pivots, formatting, tables, and resource safety

• scripts/verify_release_artifacts.py: shared wheel/sdist/MCPB content verifier used by CI and release workflows

• manifest.json: packaged MCP bundle metadata

• docs/index.html: static project landing page

Why SheetForge MCP

• Excel-first MCP surface: the toolset is focused on real .xlsx workbook operations, not generic file I/O

• agent-friendly responses: consistent JSON envelopes, compact writes, and dry_run previews reduce context waste

• workbook introspection: profile_workbook, list_all_sheets, list_tables, and list_charts make unfamiliar spreadsheets easier to navigate

• safer edits: analyze_range_impact gives agents a read-only preflight before overwriting, deleting, or restructuring an important range, including downstream formula chains plus validation-rule and conditional-format references elsewhere in the workbook even when formulas point at the range through named ranges or structured table references

• verified transactions: apply_workbook_changeset binds a bounded operation/assertion plan to the canonical target path and exact source SHA-256, tests it on an isolated candidate, verifies cells, tables, freeze panes, autofilters, and chart placement, and replaces the source once only after all checks pass

• layout planning: find_free_canvas suggests safe empty slots for charts or dashboard blocks before you place them, defaulting to the standard chart footprint when you omit explicit sizing

• practical Excel output: formatting, print setup, worksheet protection, table upserts, chart authoring, and autofit helpers cover real reporting workflows

• Python ecosystem fit: built on openpyxl, packaged for uvx, and easy to run locally over stdio or through a deliberately gated HTTP deployment

Notes For Integrators

• stdio mode is careful not to write non-protocol text to stdout.

• All tools return structured JSON envelopes, which makes client-side parsing predictable.

• Tool responses now use compact JSON serialization to reduce MCP payload size while keeping the same envelope shape.

• read_data_from_excel(..., preview_only=True) limits the response to the first 10 rows in the selected range and marks the payload as truncated when applicable.

• read_data_from_excel(..., compact=True) omits default validation stubs for cells that do not have validation rules.

• read_data_from_excel(..., values_only=True) returns a plain 2D values array for range reads that do not need per-cell addresses or validation metadata.

• read_data_from_excel(..., max_rows=...) paginates tall rectangular ranges and returns next_start_row plus next_start_cell when more rows remain.

• read_data_from_excel(..., max_cols=...) paginates wide rectangular ranges and returns next_start_col plus next_column_start_cell when more columns remain.

• read_data_from_excel(..., cursor=...) resumes from a continuation token so agents can keep paging without recomputing the next window manually; 2D windows expose directional continuations under continuations.down and continuations.right

• read_excel_as_table(..., compact=True) minimizes the tabular payload to headers and rows unless truncation metadata is needed, while still returning dataset identity metadata

• compact tabular readers still include structure_token, content_token, and snapshot_metadata, even when the tabular payload itself is minimized

• quick_read(..., start_row=...) and read_excel_as_table(..., start_row=...) let agents paginate deep worksheets without first reading from the top.

• quick_read(..., start_col=..., end_col=...) and read_excel_as_table(..., start_col=..., end_col=...) let agents request only the relevant columns from wide worksheets instead of pulling every column into context.

• read_excel_table(..., start_col=..., end_col=...) now supports the same narrower column slices for native Excel tables, as long as the requested columns fall inside the table range.

• quick_read(..., include_headers=False), read_excel_as_table(..., include_headers=False), and read_excel_table(..., include_headers=False) let follow-up pages omit repeated header payload once the first page already established the schema.

• read_excel_table(..., start_row=...) now supports deeper pagination into native Excel tables instead of always reading from the top.

• Truncated tabular reads now return next_start_row so agents can continue paging without recalculating offsets.

• Oversized read responses now fail early with ResponseTooLargeError plus structured hints, so agents can retry with smaller ranges or pagination before the client truncates the payload.

• quick_read, read_excel_as_table, and read_excel_table can now return records plus inferred schema hints when you opt into row_mode="objects" and infer_schema=True.

• Read tools do not recalculate Excel formulas; formula cells surface as formula text such as =B2*C2, and inferred schema labels formula-backed columns as formula so agents do not mistake them for fresh numeric values.

• profile_workbook provides a single-call workbook inventory with sheet-level table, chart, protection, print, and filter metadata for faster agent orientation, and now includes chart occupied_range alongside anchors and dimensions for grid-anchored worksheet charts.

• Core mutation tools now default to compact responses on committed writes, including data writes, formatting, worksheet layout helpers, and merge/unmerge helpers. Use include_changes=True for detailed diffs.

• Token-aware structured writes now return previous_structure_token, new_structure_token, previous_content_token, new_content_token, and snapshot_metadata, which makes multi-agent or read-then-write flows safer without adding hidden workbook metadata.

• dry_run versions of those structured writes now label snapshot metadata as token_basis="dry_run_preview" and keep the on-disk file facts under source_file_*, so preview tokens are no longer mixed with live-file metadata.

• Workbook saves that go through safe_workbook(..., save=True) use a timeout-aware same-host workbook lock plus temp-file save, fsync, atomic replace, rollback-on-verification-failure, and reopen verification. Symlink paths update their real target without replacing the symlink itself. If automatic rollback fails, the recovery backup is retained and identified in the error. This protects cooperating SheetForge processes on one machine; it is not a distributed lock for cloud-sync providers.

• format_ranges batches multiple formatting operations into one workbook pass and reports per-range errors without discarding successful ranges. A failed range is rolled back to its pre-operation styles, values, comments, hyperlinks, merge state, and conditional-format rules before the batch continues.

• validate_formula_syntax performs structural token validation, checks Excel coordinate limits, and rejects risky functions such as INDIRECT, HYPERLINK, WEBSERVICE, DGET, and RTD case-insensitively. It does not calculate formulas or replace Excel's own calculation engine.

• write_data_to_excel remains a raw cell-write primitive and can store formula strings directly; use it only with trusted data, or use apply_formula when you want SheetForge's formula safety checks.

• Server logs rotate at 5 MiB with two backups instead of growing without a bound.

• autofit_columns estimates practical column widths from the current cell contents, with optional column filters and min/max bounds.

• list_charts now reports chart width and height in centimeters in addition to anchor, type, and series metadata.

• get_worksheet_protection and set_worksheet_protection add a safe worksheet-level wrapper around Excel protection flags.

• set_print_area and set_print_titles make report/export setup scriptable without dropping into raw openpyxl workbook internals.

• list_tables now returns lightweight schema metadata such as headers, row counts, and stripe settings in addition to table names and ranges.

• upsert_excel_table_rows expands native Excel table ranges automatically when it appends missing keys, refuses to grow a table into already occupied cells, and rejects append attempts when the target table has an enabled totals row.

• Core mutation tools support dry_run=True so clients can preview changes before saving a workbook.

License

MIT. See LICENSE.