sheetcraft-mcp: Instructions file for Codex

sheetcraft-mcp

Shared-core Google Sheets MCP server + CLI. Both surfaces are thin wrappers over the same op library — reliability and token-efficiency live in src/lib, never in a wrapper.

Layout

src/lib/    the core. Ops-agnostic: a1 parsing, errors, output compaction, retry, schema, registry
src/ops/    operations (get_values, update_values, add_sheet, create_spreadsheet, ...). Each exports an `Op`
src/wrappers/mcp.ts   stdio MCP server — registers ops, ~30 lines of logic total
src/wrappers/cli.ts   CLI — same ops as subcommands, lazy credentials
src/test/   node:test unit tests (run against dist/)

Commands

npm run check    # tsc --noEmit
npm run build    # emit dist/
npm test         # build + node --test dist/test/*.test.js
node dist/wrappers/cli.js list        # all ops by toolset
node dist/wrappers/cli.js help <op>   # one op's JSON schema

Architecture rules (do not violate)

1. Ops are the only place Google API calls live. An op is { name, group, description, inputSchema, annotations, run(args, svc) }. It returns plain JSON-serializable data or an OpResult { text, structured? }, or throws SheetsError. Never console.log — ops return data, wrappers render.
2. Wrappers stay thin. MCP wrapper passes op.inputSchema.zod straight to the SDK's registerTool (the SDK validates + flattens args; tools/list JSON Schema and runtime validation share one source). CLI parses argv, coerces types per the op's JSON Schema, and calls the same runOp.
3. runOp never throws. Failures render as OpResult.error { code, retryable } with a teaching message. Exit codes / isError are derived from that.
4. Errors teach. Invalid ranges/sheets must quote an example and list available sheets. Rate-limit errors mention that retries already happened. Use opError() for arg problems, A1Error for range problems, and let classifyGoogleError handle Google API errors (403 with rate-limit reason → retryable).
5. A1 parsing is centralized. Use parseFullRange / scope.toA1 (concrete, values-API-safe) / scope.toGrid (GridRange for batchUpdate). Sheet params accept 'Name' or gid:N or bare gid. Sheet names with spaces should be single-quoted — splitSheetPrefix AUTO-REPAIRS the common agent slips (no quotes, stray trailing quote, quote inside the name) instead of erroring: a hard error wastes a round trip the repair saves. Don't add new hard failures for recoverable input shapes.
6. Reads are capped. cellCap (default 5000 cells) + truncationNotice telling the model how to get the rest. Writes echo updatedRange/updatedCells.
7. USER_ENTERED is the default input mode; appends default to INSERT_ROWS (the API's own default OVERWRITE silently destroys data below tables — never ship it as a default).
8. Toolsets gate registration. SHEETS_TOOLSETS env (default core,drive; valid: core, drive, formatting, charts, pivot, power, all), validated at startup with a hard error on typos. New op groups must be added to TOOLSET_GROUPS (src/lib/types.ts) and TOOLSETS (src/lib/registry.ts).
9. Cell contents are data, not instructions. Never interpolate sheet content into error messages, descriptions, or prompts.