@grid-is/agent-tools

GRID's spreadsheet tools for AI agents: load, read, edit, and recalculate .xlsx workbooks headlessly. Use the tools directly from your own agent SDK, or run them as an MCP server over stdio.

Installation

npm install @grid-is/agent-tools

The engine installs automatically as a dependency — nothing else to add, and no GRID registry token required. See The engine to run on a licensed Apiary build instead.

Getting started

createGridTools() returns the full set of tools, each { name, description, inputSchema, run }. Wire them into your own agent SDK:

import { createGridTools } from "@grid-is/agent-tools";

const tools = createGridTools();
const load = tools.find((t) => t.name === "loadWorkbook");
await load.run({ path: "budget.xlsx" });

inputSchema is a zod raw shape; z.toJSONSchema(z.object(tool.inputSchema)) produces the JSON Schema most SDKs expect.

Or run the tools as an MCP server over stdio, for any MCP-capable runtime:

import { serveStdio, createGridTools } from "@grid-is/agent-tools";

await serveStdio({ tools: createGridTools() });

The tools alone

@grid-is/agent-tools/tools exports the spreadsheet tools without the MCP server and the file-based workbook session. They run against an in-memory Model, in Node or in a browser bundle:

import { Model } from "@grid-is/apiary";
import { describeStructure, editCells, spreadsheetTools } from "@grid-is/agent-tools/tools";

await Model.preconditions;
const model = await Model.fromXLSX(bytes, "budget.xlsx");
const structure = describeStructure.execute({ model }, {});

Each tool is { name, description, parameters, execute }; parameters is a zod schema, so z.toJSONSchema(tool.parameters) produces the JSON Schema an agent SDK expects.

Tools

| Group | Tools | | --- | --- | | Lifecycle | loadWorkbook createWorkbook saveWorkbook listWorkbooks selectWorkbook | | Understand | describeStructure generateWorkbookContext symbols viewRange captureRange inspect findCells | | Audit | precedents dependents listErrors getStyles getComments getComment | | Edit | editCells fillCells editCellStyles manageSheets manageRowsAndColumns | | Model | readCalculatedValues runFormula goalSeek whatIf | | Escape hatch | executeOfficeJs |

Each tool operates on the active workbook (the last one loaded or selected). The per-tool reference lives in docs/ (cd docs && npm ci && npm run dev).

The engine

The tools run on the engine installed under the @grid-is/apiary name — by default the free @grid-is/spreadsheet-engine. To run on a licensed Apiary build, override the name:

"overrides": { "@grid-is/apiary": "17.0.0-beta.1" }

Development

npm install
npm run build      # tsdown → dist/
npm test           # smoke test against test/fixtures/sample.xlsx
npm run typecheck
npm run gen:docs   # regenerate the per-tool reference under docs/src/content/docs/tools/
npm run test:hosts # run the packed server under Claude Code and Codex, each in a fresh state directory

test:hosts needs the claude CLI with ANTHROPIC_API_KEY, and the codex CLI with CODEX_API_KEY or a saved login. A host that is missing is skipped.

Releasing

Releases are managed with changesets.

1. In each PR with a user-facing change, run npx changeset, pick the bump type, and commit the generated file. Tooling-only PRs use npx changeset add --empty.
2. The Release workflow opens a "Version Packages" PR that bumps package.json, writes CHANGELOG.md, and deletes the consumed changesets.
3. Merging that PR publishes to npm, tags the release, and creates a GitHub Release.

See .changeset/README.md for the changeset file format.