@grid-is/agent-tools 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @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
+
+```sh
+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](#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:
+
+```js
+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:
+
+```js
+import { serveStdio, createGridTools } from "@grid-is/agent-tools";
+
+await serveStdio({ tools: createGridTools() });
+```
+
+## Tools
+
+| Group | Tools |
+| --- | --- |
+| Lifecycle | `loadWorkbook` `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` *(optional — needs `@grid-is/apiary-officejs`)* |
+
+Each tool operates on the active workbook (the last one loaded or selected). The
+per-tool reference lives in [`docs/`](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`](https://www.npmjs.com/package/@grid-is/spreadsheet-engine).
+To run on a licensed Apiary build, override the name:
+
+```json
+"overrides": { "@grid-is/apiary": "17.0.0-beta.1" }
+```
+
+## Development
+
+```sh
+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/
+```