excel-mcp-server 2.2.0__tar.gz → 2.2.2__tar.gz

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excel-mcp-server
-Version: 2.2.0
+Version: 2.2.2
 Summary: MCP server for creating, reading and editing Excel workbooks without Microsoft Excel
 Keywords: mcp,mcp-server,model-context-protocol,excel,xlsx,xlsm,spreadsheet,openpyxl,charts,pivot-table,formulas,vba,llm,ai,claude,cursor
 Author: Haris Musa
@@ -23,7 +23,7 @@ Classifier: Typing :: Typed
 Requires-Dist: mcp>=2.2,<3
 Requires-Dist: olefile>=0.47,<1
 Requires-Dist: openpyxl>=3.1.5,<4
-Requires-Dist: pillow>=12,<13
+Requires-Dist: pillow>=13,<14
 Requires-Dist: pydantic>=2.12,<3
 Requires-Dist: starlette>=1,<2
 Requires-Dist: uvicorn>=0.31,<1
@@ -98,6 +98,9 @@ Excel**, and runs on Windows, macOS and Linux.
 **Large files**
 - Reads stream the workbook and return pages, so memory stays flat on sheets with hundreds of
   thousands of rows; every call is bounded by size and cell limits
+- Edits of a sheet of 1 MB of XML or more parse only the rows they touch, so inserting or
+  deleting rows and columns, sorting, replacing, copying a sheet and creating a PivotTable
+  take seconds on a 200,000-row sheet instead of minutes
 
 **Macros (opt-in)**
 - Read the VBA code in `.xlsm` files. Writing VBA is off unless you start the server with
@@ -231,6 +234,7 @@ docker run -p 8017:8017 -v "$PWD/workbooks:/data" -e EXCEL_MCP_AUTH_TOKEN=change
 | `--max-file-mb N` | `EXCEL_MCP_MAX_FILE_MB` | `100` | Largest workbook the server opens. Also sets the unpacked-size limit (10 times this) that every opened or uploaded workbook must stay under; parts compressed over 500:1 are refused |
 | `--max-cells N` | `EXCEL_MCP_MAX_CELLS` | `100000` | Most cells one call may read, write or format; reads are still returned in pages |
 | `--max-pivot-cells N` | `EXCEL_MCP_MAX_PIVOT_CELLS` | `3000000` | Largest PivotTable source in cells (a 230,000-row, 13-column sheet); creating one from the biggest sources takes a minute and about 2 GB of memory |
+| `--max-loaded-cells N` | `EXCEL_MCP_MAX_LOADED_CELLS` | `3000000` | Most cells and rows of a workbook that may be loaded into memory at once, about 0.5 KB each (a 3,000,000 limit is about 1.5 GB). A workbook with more is refused by the tools that must load whole sheets; `read_range` and the other streaming reads, and edits of large sheets that parse only some rows, are not limited by the size of the sheet |
 | `--log-level LEVEL` | | `WARNING` | Logging on stderr |
 | `--host HOST` | `EXCEL_MCP_HOST` | `127.0.0.1` | HTTP listen address |
 | `--port PORT` | `EXCEL_MCP_PORT` | `8017` | HTTP port |

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/README.md

@@ -62,6 +62,9 @@ Excel**, and runs on Windows, macOS and Linux.
 **Large files**
 - Reads stream the workbook and return pages, so memory stays flat on sheets with hundreds of
   thousands of rows; every call is bounded by size and cell limits
+- Edits of a sheet of 1 MB of XML or more parse only the rows they touch, so inserting or
+  deleting rows and columns, sorting, replacing, copying a sheet and creating a PivotTable
+  take seconds on a 200,000-row sheet instead of minutes
 
 **Macros (opt-in)**
 - Read the VBA code in `.xlsm` files. Writing VBA is off unless you start the server with
@@ -195,6 +198,7 @@ docker run -p 8017:8017 -v "$PWD/workbooks:/data" -e EXCEL_MCP_AUTH_TOKEN=change
 | `--max-file-mb N` | `EXCEL_MCP_MAX_FILE_MB` | `100` | Largest workbook the server opens. Also sets the unpacked-size limit (10 times this) that every opened or uploaded workbook must stay under; parts compressed over 500:1 are refused |
 | `--max-cells N` | `EXCEL_MCP_MAX_CELLS` | `100000` | Most cells one call may read, write or format; reads are still returned in pages |
 | `--max-pivot-cells N` | `EXCEL_MCP_MAX_PIVOT_CELLS` | `3000000` | Largest PivotTable source in cells (a 230,000-row, 13-column sheet); creating one from the biggest sources takes a minute and about 2 GB of memory |
+| `--max-loaded-cells N` | `EXCEL_MCP_MAX_LOADED_CELLS` | `3000000` | Most cells and rows of a workbook that may be loaded into memory at once, about 0.5 KB each (a 3,000,000 limit is about 1.5 GB). A workbook with more is refused by the tools that must load whole sheets; `read_range` and the other streaming reads, and edits of large sheets that parse only some rows, are not limited by the size of the sheet |
 | `--log-level LEVEL` | | `WARNING` | Logging on stderr |
 | `--host HOST` | `EXCEL_MCP_HOST` | `127.0.0.1` | HTTP listen address |
 | `--port PORT` | `EXCEL_MCP_PORT` | `8017` | HTTP port |

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "excel-mcp-server"
-version = "2.2.0"
+version = "2.2.2"
 description = "MCP server for creating, reading and editing Excel workbooks without Microsoft Excel"
 readme = "README.md"
 license = "MIT"
@@ -43,7 +43,7 @@ dependencies = [
     "mcp>=2.2,<3",
     "olefile>=0.47,<1",
     "openpyxl>=3.1.5,<4",
-    "pillow>=12,<13",
+    "pillow>=13,<14",
     "pydantic>=2.12,<3",
     "starlette>=1,<2",
     "uvicorn>=0.31,<1",
@@ -71,7 +71,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.12.19,<0.13"]
+requires = ["uv_build>=0.13.1,<0.14"]
 build-backend = "uv_build"
 
 [tool.ruff]

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "excel-mcp-server"
-version = "2.2.0"
+version = "2.2.2"
 description = "MCP server for creating, reading and editing Excel workbooks without Microsoft Excel"
 readme = "README.md"
 license = "MIT"
@@ -44,7 +44,7 @@ dependencies = [
     "mcp>=2.2,<3",
     "olefile>=0.47,<1",
     "openpyxl>=3.1.5,<4",
-    "pillow>=12,<13",
+    "pillow>=13,<14",
     "pydantic>=2.12,<3",
     "starlette>=1,<2",
     "uvicorn>=0.31,<1",
@@ -68,7 +68,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.12.19,<0.13"]
+requires = ["uv_build>=0.13.1,<0.14"]
 build-backend = "uv_build"
 
 [tool.ruff]

excel_mcp_server-2.2.2/src/excel_mcp/cell_budget.py

@@ -0,0 +1,73 @@
+"""A limit on the cells that a workbook's sheets make openpyxl create.
+
+Memory use is set by the number of cells created, not by the size of the file: a sheet of
+millions of empty cells is a few hundred kilobytes. So every sheet is counted before it is
+parsed, and what is created cannot pass the limit. Rows count as cells (openpyxl keeps their
+attributes), and so does every cell of a merged range or hyperlink range, which it creates
+from the one element that names the range.
+"""
+
+from pathlib import Path
+from typing import IO
+from xml.parsers import expat
+
+from openpyxl.reader.excel import ExcelReader
+from openpyxl.xml.constants import SHEET_MAIN_NS, WORKSHEET_TYPE
+
+from excel_mcp.errors import LimitExceededError
+from excel_mcp.refs import parse_range
+
+_CHUNK = 1 << 20
+_NAMESPACE = f"{SHEET_MAIN_NS} "
+_COUNTED = {f"{_NAMESPACE}c", f"{_NAMESPACE}row"}
+_MERGED = f"{_NAMESPACE}mergeCell"
+_LINKED = f"{_NAMESPACE}hyperlink"
+# A cell that holds a link takes about three times the memory of one that does not.
+_LINK_COST = 3
+
+
+class CellBudget:
+    """The cells that may still be created for one workbook, shared by all its sheets."""
+
+    def __init__(self, limit: int) -> None:
+        self.limit = limit
+        self.used = 0
+
+    def spend(self, count: int) -> None:
+        self.used += count
+        if self.used > self.limit:
+            raise LimitExceededError(
+                f"The workbook has more than {self.limit:,} cells and rows to load, which "
+                "would use too much memory. Read it with read_range, split it into smaller "
+                "workbooks, or raise --max-loaded-cells."
+            )
+
+
+def spend_sheet(source: IO[bytes], budget: CellBudget) -> None:
+    """Spend the cells and rows of one worksheet's XML, stopping at the first one over the limit."""
+    parser = expat.ParserCreate(namespace_separator=" ")
+
+    def start(name: str, attributes: dict[str, str]) -> None:
+        if name in _COUNTED:
+            budget.spend(1)
+        elif name == _MERGED:
+            budget.spend(parse_range(attributes["ref"]).size)
+        elif name == _LINKED:
+            budget.spend(_LINK_COST * parse_range(attributes["ref"]).size)
+
+    parser.StartElementHandler = start
+    while chunk := source.read(_CHUNK):
+        parser.Parse(chunk, False)
+    parser.Parse(b"", True)
+
+
+def check_workbook(path: Path, budget: CellBudget) -> None:
+    """Spend the cells and rows that loading all of a workbook's worksheets would create."""
+    reader = ExcelReader(path)
+    try:
+        reader.read_manifest()
+        for part in reader.package.findall(WORKSHEET_TYPE):
+            with reader.archive.open(part.PartName.lstrip("/")) as source:
+                spend_sheet(source, budget)
+    finally:
+        reader.archive.close()

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/src/excel_mcp/cli.py

@@ -78,6 +78,7 @@ def _settings(args: argparse.Namespace) -> Settings:
             max_file_bytes=args.max_file_mb * MB,
             max_cells=args.max_cells,
             max_pivot_source_cells=args.max_pivot_cells,
+            max_loaded_cells=args.max_loaded_cells,
         ),
         log_level=args.log_level,
     )
@@ -159,6 +160,13 @@ def _parser() -> argparse.ArgumentParser:
         help="Largest PivotTable source, in cells (default %(default)s). "
         "Also EXCEL_MCP_MAX_PIVOT_CELLS.",
     )
+    common.add_argument(
+        "--max-loaded-cells",
+        type=_positive_int,
+        default=_env_default("EXCEL_MCP_MAX_LOADED_CELLS", DEFAULT_LIMITS.max_loaded_cells),
+        help="Most cells and rows of a workbook that may be loaded into memory at once, about "
+        "0.5 KB each (default %(default)s). Also EXCEL_MCP_MAX_LOADED_CELLS.",
+    )
     common.add_argument(
         "--log-level",
         default="WARNING",

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/src/excel_mcp/config.py

@@ -14,6 +14,8 @@ class Limits:
     max_cells: int = 100_000
     max_pivot_source_cells: int = 3_000_000
     max_copy_cells: int = 1_000_000
+    # Cells and rows that all the sheets of a workbook may create in memory, about 0.5 KB each.
+    max_loaded_cells: int = 3_000_000
     # Zip bomb guards, applied to every workbook the server opens or receives. Real workbooks
     # compress 10 to 30 times and sparse sheets far more, so these leave room for them.
     max_unpack_factor: int = 10

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/src/excel_mcp/formulas.py

@@ -16,10 +16,12 @@ else before a "!" (a file, a path, a URL, "[1]") points at another workbook.
 
 import re
 from collections.abc import Iterable, Iterator
+from functools import lru_cache
 
 from openpyxl.formula import Tokenizer
 from openpyxl.formula.tokenizer import Token, TokenizerError
 
+from excel_mcp import plain_refs
 from excel_mcp.errors import InvalidFormulaError, UnsafeFormulaError
 from excel_mcp.formula_syntax import check_syntax, invalid_formula
 from excel_mcp.spill import store_spills
@@ -118,10 +120,28 @@ def storable_formula(formula: str, sheet_names: Iterable[str]) -> str:
 
     Every formula that is written anywhere in a workbook goes through here.
     """
+    pattern = plain_refs.shape(formula)
+    if pattern is not None and _is_plain_and_allowed(pattern):
+        return formula
     check_formula(formula, sheet_names)
     return add_prefixes(store_spills(formula))
 
 
+@lru_cache(maxsize=4096)
+def _is_plain_and_allowed(pattern: str) -> bool:
+    """Whether formulas of this shape pass the check and need no prefixes.
+
+    Which cells a plain formula refers to cannot change the outcome, so a sheet with hundreds
+    of thousands of formulas filled down from a few is checked a few times, not that often.
+    A formula that does not pass is checked again as itself, to raise its own error.
+    """
+    try:
+        check_formula(pattern, ())
+    except (InvalidFormulaError, UnsafeFormulaError):
+        return False
+    return add_prefixes(pattern) == pattern
+
+
 def storable_operand(operand: str, sheet_names: Iterable[str]) -> str:
     """`storable_formula` for rule operands and names, which are stored without the "="."""
     return storable_formula(f"={operand.removeprefix('=')}", sheet_names).removeprefix("=")

{excel_mcp_server-2.2.0 → excel_mcp_server-2.2.2}/src/excel_mcp/lazy_edit.py

@@ -32,16 +32,10 @@ from openpyxl.worksheet.dimensions import DimensionHolder
 from openpyxl.worksheet.worksheet import Worksheet
 from openpyxl.xml.constants import SHARED_STRINGS
 
-from excel_mcp import lazy_shared
-from excel_mcp.lazy_workbook import (
-    BLOCK_ROWS,
-    LazyCells,
-    Parts,
-    SheetSource,
-    lazy_sheets,
-    open_lazily,
-    split_sheet,
-)
+from excel_mcp import lazy_rows, lazy_shared
+from excel_mcp.cell_budget import CellBudget
+from excel_mcp.lazy_source import SheetSource, split_sheet
+from excel_mcp.lazy_workbook import BLOCK_ROWS, LazyCells, Parts, lazy_sheets, open_lazily
 from excel_mcp.package.opc import REL_BASE, Package, Rel, free_id
 from excel_mcp.package.restore import MAIN, sheet_parts
 from excel_mcp.package.scan import declare_in_root, root_scope
@@ -148,27 +142,31 @@ class LazyEdit:
 
     path: Path
     strings_part: str | None
-    sheets: list[Worksheet] = field(default_factory=list)
-    frozen: dict[Worksheet, LazyCells] = field(default_factory=dict)
+    frozen: dict[Worksheet, tuple[LazyCells, dict[int, bytes]]] = field(default_factory=dict)
 
-    def freeze(self) -> None:
-        """Leave each sheet with the cells and row dimensions that were parsed, for saving.
+    def freeze(self, workbook: Workbook) -> None:
+        """Prepare each sheet for saving, with the rows that were parsed written as text.
 
-        openpyxl writes what a sheet holds, and the rows of blocks that were not parsed are
-        put in from the file by `merge`.
+        openpyxl writes what a sheet holds, which is only the rows that need it (those with a
+        link, a note or a value it writes in a form of its own). The other rows of blocks that
+        were parsed are written by `lazy_rows`, and the rows of blocks that were not parsed are
+        put in from the file; `merge` puts them all together.
         """
-        for sheet in self.sheets:
+        for sheet in workbook.worksheets:
             cells = sheet._cells
-            if isinstance(cells, LazyCells):
-                lazy_shared.settle(cells)
+            if not isinstance(cells, LazyCells):
+                continue
+            lazy_shared.settle(cells)
             dimensions = DimensionHolder(worksheet=sheet, default_factory=sheet._add_row)
             for row, dimension in dict.items(sheet.row_dimensions):
-                if not isinstance(cells, LazyCells) or cells.is_loaded(row):
+                if cells.is_loaded(row):
                     dimensions[row] = dimension
-            sheet.row_dimensions = dimensions
-            if isinstance(cells, LazyCells):
-                sheet._cells = cells.held()
-                self.frozen[sheet] = cells
+            rendered, sheet._cells = lazy_rows.render(cells.held(), dimensions)
+            kept = {row for row, _ in sheet._cells}
+            sheet.row_dimensions = DimensionHolder(worksheet=sheet, default_factory=sheet._add_row)
+            for row in kept & dimensions.keys():
+                sheet.row_dimensions[row] = dimensions[row]
+            self.frozen[sheet] = (cells, rendered)
 
     def merge(self, workbook: Workbook, content: bytes) -> bytes:
         """The saved workbook with the rows that were not parsed put back, as the file has them."""
@@ -179,8 +177,9 @@ class LazyEdit:
             return content
         package = Package(content)
         parts = sheet_parts(package)
-        for sheet, cells in spliced.items():
-            package.write(parts[sheet.title], _splice(package.read(parts[sheet.title]), cells))
+        for sheet, (cells, rendered) in spliced.items():
+            xml = _splice(package.read(parts[sheet.title]), cells, rendered)
+            package.write(parts[sheet.title], xml)
         if self.strings_part:
             self._restore_strings(package)
         return package.to_bytes()
@@ -199,22 +198,22 @@ class LazyEdit:
         rels.append(Rel(free_id(rels, ""), REL_BASE + "sharedStrings", name))
 
 
-def load(path: Path) -> tuple[Workbook, LazyEdit | None]:
+def load(path: Path, budget: CellBudget) -> tuple[Workbook, LazyEdit | None]:
     """Load a workbook for editing, its large sheets without their rows."""
     parts: Parts = {}
-    reader = open_lazily(path, parts, _split)
+    reader = open_lazily(path, parts, _split, budget)
     reader.read()
     strings = reader.package.find(SHARED_STRINGS)
     edit = LazyEdit(path, strings.PartName.lstrip("/") if strings is not None else None)
-    for sheet, source in lazy_sheets(reader, parts):
-        _install(sheet, source, reader.shared_strings)
-        edit.sheets.append(sheet)
-    return reader.wb, edit if edit.sheets else None
+    lazy = list(lazy_sheets(reader, parts))
+    for sheet, source in lazy:
+        _install(sheet, source, reader.shared_strings, budget)
+    return reader.wb, edit if lazy else None
 
 
-def _install(sheet: Worksheet, source: SheetSource, strings: list[str]) -> None:
+def _install(sheet: Worksheet, source: SheetSource, strings: list[str], budget: CellBudget) -> None:
     carried = sheet._cells
-    cells = LazyCells(sheet, source, strings)
+    cells = LazyCells(sheet, source, strings, budget)
     sheet._cells = cells
     _bind_row_dimensions(sheet, source, strings)
     for (row, column), carried_cell in carried.items():
@@ -250,13 +249,14 @@ def _self_closed(tag: bytes) -> bytes:
     return tag if tag.endswith(b"/>") else tag[:-1] + b"/>"
 
 
-def _splice(xml: bytes, cells: LazyCells) -> bytes:
+def _splice(xml: bytes, cells: LazyCells, rendered: dict[int, bytes]) -> bytes:
     """The sheet openpyxl wrote, holding the rows of the parsed blocks, with the others added."""
     source = cells.source
     data = _SHEET_DATA.search(xml)
     if data is None:
         raise ValueError("A saved worksheet has no sheetData.")
     produced = {_row_number(row[0]): row[0] for row in _ROW.finditer(data[0])}
+    produced.update(rendered)
     lazy_shared.restore(cells, produced)
     pieces = _rows(cells, produced)
     head, tail = xml[: data.start()], xml[data.end() :]

excel_mcp_server-2.2.2/src/excel_mcp/lazy_find.py

@@ -0,0 +1,83 @@
+"""Finding which rows of a sheet that is not parsed can hold a text, without parsing them.
+
+Replacing text looks at every cell, but most of a large sheet holds none of it. Only the blocks
+of rows that might hold a match are parsed; the others are as in the file. "Might" is decided
+from the XML and errs on the side of parsing: a block that holds nothing is parsed at worst.
+A cell is searched as `replace` searches it: text, numbers as their text, formulas as they are
+written (without the storage prefixes), so a formula that is only a master of the shared
+formulas below it matches for the cells that follow it too.
+"""
+
+import re
+from bisect import bisect_right
+from collections.abc import Callable
+from html import unescape
+
+from excel_mcp.lazy_workbook import LazyCells
+
+_STRING = re.compile(rb'<c\b[^>]*\bt="s"[^>]*><v>(\d+)</v>')
+_INLINE = re.compile(rb"<is>(.*?)</is>", re.S)
+_TAGS = re.compile(rb"<[^>]*>")
+_FORMULA = re.compile(rb"<f\b([^>]*)>([^<]*)</f>")
+_NUMBER = re.compile(rb'<c\b(?![^>]*\bt="(?!n")\w+")[^>]*><v>')
+_GROUP = re.compile(rb'\bsi="(\d+)"')
+_TEXT_OF_NUMBERS = frozenset("0123456789.-+e")
+# What a stored formula has and its text as shown does not, or the reverse.
+_STORAGE_MARKS = ("_xl", "anchorarray")
+
+
+def load_matches(
+    cells: LazyCells, matches: Callable[[str], bool], query: str, *, in_formulas: bool
+) -> None:
+    """Parse the blocks that may hold a cell for which ``matches(text)`` is true.
+
+    ``query`` is what ``matches`` looks for, which tells what kinds of cell it can match.
+    """
+    source = cells.source
+    starts = [start for start, _ in source.spans]
+    rows: set[int] = set()
+
+    def mark(position: int) -> None:
+        rows.add(source.row_numbers[bisect_right(starts, position) - 1])
+
+    hits = {index for index, text in enumerate(cells.strings) if matches(text)}
+    if hits:
+        for found in _STRING.finditer(source.data):
+            if int(found[1]) in hits:
+                mark(found.start())
+    for found in _INLINE.finditer(source.data):
+        if matches(unescape(_TAGS.sub(b"", found[1]).decode())):
+            mark(found.start())
+    if set(query.lower()) <= _TEXT_OF_NUMBERS:
+        rows.update(_rows_with_numbers(cells))
+    if in_formulas:
+        _mark_formulas(cells, matches, query, mark)
+    for number in rows:
+        cells.load(number)
+
+
+def _rows_with_numbers(cells: LazyCells) -> list[int]:
+    source = cells.source
+    return [
+        number
+        for number, (start, stop) in zip(source.row_numbers, source.spans, strict=True)
+        if _NUMBER.search(source.data, start, stop)
+    ]
+
+
+def _mark_formulas(
+    cells: LazyCells, matches: Callable[[str], bool], query: str, mark: Callable[[int], None]
+) -> None:
+    source = cells.source
+    digits = any(character.isdigit() for character in query)
+    for found in _FORMULA.finditer(source.data):
+        shown = "=" + unescape(found[2].decode())
+        hit = matches(shown) or any(part in shown.lower() for part in _STORAGE_MARKS)
+        if hit:
+            mark(found.start())
+        group = _GROUP.search(found[1])
+        master = source.masters.get(group[1].decode()) if group else None
+        # A cell that follows its master differs from it in digits, and in letters when the
+        # group spans columns.
+        if master is not None and (hit or digits or master.wide):
+            cells.load_between(*master.rows)