---

spreadsheet-kit

spreadsheet-kit — это сервис взаимодействия с инструментами для работы агентов с электронными таблицами.

Он даёт агентам безопасный, проверяемый и экономный по токенам способ читать, анализировать, изменять, верифицировать и применять книги Excel в реальной работе без обращения к хрупкой автоматизации пользовательского интерфейса.

Если вы хотите, чтобы агент работал с таблицами как настоящая система, а не как марионетка, управляемая скриншотами, — это именно тот стек.

---

Что это за проект

spreadsheet-kit поставляет единый слой взаимодействия с таблицами на четырёх поверхностях:

Поверхность	Бинарник / Пакет	Режим	Лучше всего подходит для
CLI	asp / agent-spreadsheet	Без состояния	Одноразовые чтения, безопасные правки, пайплайны, CI, вызовы инструментов агентом
MCP-сервер	spreadsheet-mcp	С состоянием	Многоходовые сессии агента, кэширование книг, рабочие процессы fork/recalc
JS SDK	spreadsheet-kit-sdk	Не зависит от бэкенда	Интеграции в приложения, которые сегодня могут работать через MCP, а со временем — через WASM/сессионные бэкенды
WASM-рантайм	spreadsheet-kit-wasm	Внутрипроцессный	Экспериментальное встраивание байтов/сессий для локальных рантаймов

Поддерживаемые режимы работы с книгами:

• .xlsx / .xlsm — чтение + запись
• .xls / .xlsb — только рабочие процессы обнаружения/чтения

---

Почему агенты используют spreadsheet-kit

Создан для использования инструментами, а не только людьми

• детерминированные JSON-контракты
• обнаружение схем и примеров прямо из самого CLI
• явная пагинация и компактные режимы вывода
• машиночитаемые предупреждения и конверты ошибок

Безопасное изменение, а не слепое изменение

• сначала пробный запуск (dry-run)
• режимы вывода без состояния и защита от перезаписи
• редактирование сессий на основе событий (event sourcing)
• поверхности верификации для доказательства последующих результатов
• анализ структурного воздействия перед рискованными изменениями книги

Осведомлённость о структуре таблиц, а не универсальное редактирование файлов

• определение регионов
• помощники добавления с учётом таблиц и футеров
• клонирование строк шаблона / полос строк
• специфичная для формул замена и диагностика
• CRUD именованных диапазонов
• потоки пересчёта + diff + подтверждения

Хорошая эргономика для агентов

• вложенные группы команд с совместимостью устаревших псевдонимов
• экономные по токенам операции чтения
• инспекция конкретных ячеек и инспекция макета
• помощники рабочих процессов для повторяющихся частей, в которых агенты обычно ошибаются

---

Что нового / чем этот стек отличается

Текущая поверхность гораздо мощнее простого инструмента «прочитать несколько ячеек». Основные возможности теперь включают:

• asp как основной CLI, где 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 + выполнение для автоматизации таблиц на основе контрактов

---

Установка

npm (рекомендуется для CLI)

npm i -g agent-spreadsheet
asp --help

Устанавливает оба: - asp — основную команду - agent-spreadsheet — псевдоним совместимости

Загружает предсобранный нативный бинарник для вашей платформы. Инструментарий Rust не требуется.

Cargo

# CLI
cargo install spreadsheet-kit --features recalc --bin asp --bin agent-spreadsheet

# MCP server
cargo install spreadsheet-mcp

Formualizer (нативный движок пересчёта на Rust) включён по умолчанию.

Docker

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

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

JavaScript SDK

npm i spreadsheet-kit-sdk

Предсобранные бинарники

Загрузите из GitHub Releases.

Опубликованные нативные артефакты включают: - Linux x86_64 - macOS x86_64 - macOS arm64 - Windows x86_64

---

Начните отсюда: основные рабочие процессы

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) Выполняйте цикл: безопасная правка без состояния → пересчёт → подтверждение → diff

---

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 schema write batch transform
asp example write batch transform
asp schema session op transform.write_matrix
asp example session op transform.write_matrix

Это ключевой принцип проектирования: интерфейс должен объяснять себя агенту самостоятельно.

---

Семейства команд

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> ...	Импорт grid json или csv в диапазон книги
asp write append ...	Добавление строк с учётом футера в регион или таблицу
asp write clone-template-row ...	Клонирование строки-шаблона с планированием «сначала предпросмотр»
asp write clone-row-band ...	Многократное клонирование многострочного шаблонного блока
asp write formulas replace ...	Поиск/замена только формул на листе/в диапазоне
asp write name define|update|delete ...	Помощники для изменения именованных диапазонов
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>

Это важно для агентов, поскольку позволяет: - планирование в режиме dry-run - неразрушающее выполнение - явный контроль перезаписи

Поддержка формул

Изменение формул теперь является полноценным интерфейсом первого класса:

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>	Сравнение книг со сводкой на первом месте, группировкой и опциональной постраничной детализацией

Почему верификация важна

Большинство инструментов автоматизации электронных таблиц останавливаются на «правка применена».

spreadsheet-kit идёт дальше: - изменились ли целевые ячейки так, как мы ожидали? - не появились ли в книге новые ошибки? - какие изменения были прямыми правками, а какие — побочными эффектами пересчёта? - что изменилось в целом, сгруппированное так, чтобы агент мог это осмыслить?

Этот слой верификации — значительная часть того, почему этот проект является серьёзной основой для агентов, а не утилитарным скриптом.

---

session — редактирование с состоянием на основе событий

Интерфейс сессий предназначен для рабочих процессов, которые слишком сложны для одного изменения без сохранения состояния.

Что дают сессии

• постоянное состояние редактирования
• поэтапные операции dry-run
• семантика применения compare-and-swap
• журналы и воспроизводимость
• потоки ветвления/переключения/форкинга
• отмена / повтор / checkout
• явная материализация обратно в файл книги

Канонический цикл

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: возвращает стабильную оболочку values: [...] как в каноническом, так и в компактном режиме. - range-values кодировка по умолчанию: плотный JSON (dense.encoding = "dense_v1") с dictionary + кодированием длин серий row_runs. - range-values --include-formulas: включает разреженные координаты формул в плотном режиме (dense.formulas) или матрицу в явном формате json. - read-table и sheet-page: compact сохраняет активную ветку и поля продолжения (next_offset, next_start_row). - formula-trace compact: опускает послойные highlights, сохраняя layers и next_cursor.

Детерминированные циклы пагинации

# 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. Запросите страницу 1 без --start-row.

---

1. Если присутствует next_start_row, снова вызовите sheet-page с --start-row ```html <next_start_row>.
2. Остановитесь, когда 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":[...]} и также принимает sheet_name для каждой отдельной операции внутри {"ops":[...]}.

Полезные нагрузки 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-pattern (@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. Сравните `write_path_provenance.written_via` и `formula_targets` в ответах.
3. Используйте `inspect-cells` вместе с `recalculate`, чтобы сравнить итоговое поведение.

#### Стартовые настройки по умолчанию для финансовых презентаций
- Явно задавайте ширину столбцов с подписями (обычно столбец A) (примерно `24–36` символов), чтобы избежать обрезки текста.
- Применяйте единообразные числовые форматы по смысловому типу:
  - Валюта: `"$"#,##0.00_);[Red](https://github.com/PSU3D0/spreadsheet-mcp/blob/main/"$"#,##0.00)`
  - Проценты: `0.0%`
  - Целые числа/количество: `#,##0`
- Применяйте закрепление областей через `sheet-layout-batch` после стабилизации макета заголовков.

JSON-вывод по умолчанию компактный; используйте `--quiet`, чтобы подавить предупреждения.
Глобальный параметр `--output-format csv` в настоящее время не поддерживается; используйте специфичные для команд CSV-опции, например `read table --table-format csv`.

---

## Быстрый старт с MCP-сервером

MCP-интерфейс — это версия spreadsheet-kit в виде сервера с сохранением состояния.

Используйте его, если вам нужны:
- кэширование рабочих книг между вызовами
- жизненный цикл форков вместо замены файлов без сохранения состояния
- многошаговые рабочие процессы агентов
- скриншоты и более богатая оркестрация на стороне сервера

### Claude Code / Claude Desktop

Добавьте в `~/.claude.json` или проектный `.mcp.json`:

```json
{
  "mcpServers": {
    "spreadsheet": {
      "command": "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/spreadsheet-mcp:latest-full",
        "--transport", "stdio"
      ]
    }
  }
}

:latest — это облегчённый образ только для чтения (инструменты записи/форков/пересчёта отключены); :latest-full включает инструменты записи и пересчёт (на базе LibreOffice).

HTTP-режим

spreadsheet-mcp --workspace-root /path/to/workbooks
# -> http://127.0.0.1:8079  (POST /mcp)

Конфигурация

Каждый параметр доступен как флаг CLI (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_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

Чтение и обнаружение

• list_workbooks
• describe_workbook
• list_sheets
• workbook_summary
• sheet_overview
• sheet_page
• read_table
• range_values
• inspect_cells — детальный просмотр до 25 отдельных ячеек с полными метаданными (значение, формула, стиль, числовой формат)
• layout_page — отрисовка диапазона листа с семантикой макета (ширины столбцов, границы, объединения) в виде JSON и опционально ASCII-сетки
• grid_export — экспорт диапазона в виде расширенной сетки со значениями, формулами, числовыми форматами, стилями, размерами столбцов и объединениями для каждой ячейки
• named_ranges
• sheet_styles
• workbook_style_summary
• close_workbook — выгрузить книгу из кэша

Поиск и анализ

• find_value
• find_formula
• sheet_formula_map
• formula_trace
• scan_volatiles
• table_profile
• sheet_statistics
• get_manifest_stub
• execute_manifest — выполнить манифест SheetPort с JSON-входными данными

Верификация

• verify_workbook — сравнить базовую/текущую книгу или идентификаторы форков и выдать целевое доказательство плюс новые/устранённые/существовавшие ранее ошибки; шаг доказательства со сводкой в начале после recalculate

Запись с сохранением состояния и пересчёт

• жизненный цикл форка
• контрольные точки
• edit_batch
• transform_batch
• style_batch
• grid_import — импорт расширенной сетки данных (значения, формулы, стили, форматы, размеры столбцов, объединения)
• apply_formula_pattern
• structure_batch
• column_size_batch
• sheet_layout_batch
• rules_batch
• define_name / update_name / delete_name — управление именованными диапазонами в форке
• replace_in_formulas — поиск и замена текста только в телах формул, обычный текст или регулярное выражение, предпросмотр или применение
• recalculate
• get_edits — перечислить все правки, применённые к форку
• get_changeset
• save_fork
• управление промежуточными изменениями
• screenshot_sheet

Инспекция VBA

• vba_project_summary
• vba_module_source

---

Статус JS SDK и WASM

spreadsheet-kit-sdk

JS SDK — это слой интеграции для приложений.

Он нормализует: - названия методов - алиасы входных данных - структуры выходных данных - типизированные ошибки возможностей

Он спроектирован так, чтобы интеграция могла работать с: - бэкендами MCP уже сейчас - бэкендами WASM/сессий по мере их созревания во встраиваемых средах выполнения

Установка:

npm i spreadsheet-kit-sdk

spreadsheet-kit-wasm

Крейт на Rust существует в этом репозитории и предоставляет ориентированную на WASM обёртку байтов/сессий над общим движком.

Текущий статус: - крейт существует и тестируется внутри репозитория - он ещё не опубликован как универсальный публичный пакет - дистрибуция npm-пакета spreadsheet-kit-wasm остаётся запланированной

Поэтому правильная формулировка сегодня такова: - WASM реально работает внутри репозитория - публичная дистрибуция и более широкая упаковка всё ещё развиваются

---

Бэкенды пересчёта

Пересчёт формул подключаемый.

Бэкенд	Как	По умолчанию	Лучше всего подходит для
Formualizer	Собственный движок на Rust	Да	Быстрый пересчёт по умолчанию без внешних зависимостей
LibreOffice	Запуск soffice без графического интерфейса	Docker :latest-full / явные сборки	Максимальная совместимость и сценарии со скриншотами

Примечания по функциям: - recalc-formualizer включён по умолчанию - recalc-libreoffice доступен для сборок с поддержкой LibreOffice - чтение и многие операции записи работают без пересчёта; только сам пересчёт требует бэкенда

---

Docker-образы

Публикуются в ghcr.io/psu3d0/spreadsheet-mcp:

Образ	Размер	Пересчёт	Лучше всего подходит для
latest	~15 МБ	Нет	Анализ в режиме только чтения и лёгкие развёртывания агентов
latest-full	~800 МБ	Да	Запись + пересчёт + скриншоты

Примеры:

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

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

---

Структура рабочего пространства

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

Роли пакетов

Пакет	Роль
spreadsheet-kit	общий движок и исполняемые файлы CLI
spreadsheet-mcp	MCP-транспорт с сохранением состояния + серверная поверхность
spreadsheet-kit-wasm	ориентированная на WASM обёртка байтов/сессий
agent-spreadsheet	npm-обёртка для бинарника CLI
spreadsheet-kit-sdk	JS SDK для интеграций в стиле MCP/WASM

---

Заметки об архитектуре

Основные идеи: - единое семантическое ядро, общее для 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/spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

---

Подробнее

---

• README CLI-пакета: npm/agent-spreadsheet
• README основного крейта: crates/spreadsheet-kit
• README MCP-крейта: crates/spreadsheet-mcp
• README JS SDK: npm/spreadsheet-kit-sdk
• README WASM-обёртки: crates/spreadsheet-kit-wasm
• Примечания по упаковке и версионированию: docs/PACKAGING.md
• Эвристики и определение региона: docs/HEURISTICS.md
• Архитектура пересчёта: docs/RECALC.md

---

Лицензия

Apache-2.0