@sheetpane/mcp 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { handle, LATEST, SUPPORTED, SERVER_INFO, type Request, type Response } from './protocol.js';
+export { TOOLS, callTool, inspectWorkbook, draftRules, checkRules, explainCode, findSkill, guessHeaderRow, type Tool, type ToolResult } from './tools.js';
+export { describeApi } from './api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1J,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// @sheetpane/mcp (W-39): the server's message handler and its tools, for embedding or testing;
+// `sheetpane-mcp` (bin.ts) runs it over stdio.
+export { handle, LATEST, SUPPORTED, SERVER_INFO } from './protocol.js';
+export { TOOLS, callTool, inspectWorkbook, draftRules, checkRules, explainCode, findSkill, guessHeaderRow } from './tools.js';
+export { describeApi } from './api.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,+CAA+C;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAA+B,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAA8B,MAAM,YAAY,CAAC;AAC1J,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/plugins.json

@@ -0,0 +1,50 @@
+[
+  {
+    "id": "charts",
+    "package": "@sheetpane/charts",
+    "description": "Charts for sheetpane — a frame at the chart's anchor with its title and Show source cells; later, own SVG for bar, column, line, pie and scatter — through the `overlay` hook.",
+    "record": "records/0113_CHARTS.md"
+  },
+  {
+    "id": "comments",
+    "package": "@sheetpane/comments",
+    "description": "Comments and notes for sheetpane — the file's notes and threaded comments read into the error pane; every sheetpane error written back as a threaded comment on export.",
+    "record": "records/0112_COMMENTS.md"
+  },
+  {
+    "id": "condfmt",
+    "package": "@sheetpane/condfmt",
+    "description": "Conditional formatting for sheetpane — cellIs, containsText, duplicates, top10, colour scales, data bars — rendered through the `decorate` hook after @sheetpane/styles.",
+    "record": "records/0114_CONDFMT.md"
+  },
+  {
+    "id": "formulas",
+    "package": "@sheetpane/formulas",
+    "description": "Formula recalculation for sheetpane — edit a cell and every dependent formula updates — as a plugin on the `derive` hook, backed by IronCalc (WASM, lazy-loaded).",
+    "record": "records/0111_FORMULAS.md"
+  },
+  {
+    "id": "images",
+    "package": "@sheetpane/images",
+    "description": "Images for sheetpane — pictures anchored in the sheet drawn in sheet space through the `overlay` hook; view only, kept on export.",
+    "record": "records/0107_IMAGES.md"
+  },
+  {
+    "id": "numfmt",
+    "package": "@sheetpane/numfmt",
+    "description": "Excel number formats for sheetpane — currency, dates, fractions, elapsed time, conditional sections, locales — as a plugin on the `format` hook.",
+    "record": "records/0109_NUMFMT.md"
+  },
+  {
+    "id": "styles",
+    "package": "@sheetpane/styles",
+    "description": "Cell styles for sheetpane — fill, bold, italic, underline, colour, borders, alignment, wrap — as a plugin on the `decorate` hook. Never a font family (SR-LAW-5).",
+    "record": "records/0110_STYLES.md"
+  },
+  {
+    "id": "validation",
+    "package": "@sheetpane/validation",
+    "description": "Data validation for sheetpane — the workbook's own `<dataValidations>` rules checked on load and on every edit, landing in <sheetpane-errors> — as a plugin on the `validate` hook.",
+    "record": "records/0108_VALIDATION.md"
+  }
+]

package/dist/protocol.d.ts

@@ -0,0 +1,29 @@
+export declare const LATEST = "2026-07-28";
+export declare const SUPPORTED: readonly ["2026-07-28", '2025-11-25', '2025-06-18'];
+export declare const SERVER_INFO: {
+    name: string;
+    title: string;
+    version: string;
+};
+export interface Request {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: {
+        _meta?: Record<string, unknown>;
+        [k: string]: unknown;
+    };
+}
+export interface Response {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Answers one message; a notification (no `id`) gets no answer. */
+export declare function handle(msg: unknown): Promise<Response | undefined>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,MAAM,eAAe,CAAC;AACnC,eAAO,MAAM,SAAS,0BAAY,YAAY,EAAE,YAAY,CAAU,CAAC;AACvE,eAAO,MAAM,WAAW;IAAK,IAAI;IAAmB,KAAK;IAAe,OAAO;CAAW,CAAC;AAI3F,MAAM,WAAW,OAAO;IAAG,OAAO,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CAAE;AAC5J,MAAM,WAAW,QAAQ;IAAG,OAAO,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE;AAMrJ,oEAAoE;AACpE,wBAAsB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAiCxE"}

package/dist/protocol.js

@@ -0,0 +1,52 @@
+// A Model Context Protocol server over stdio, hand-written (W-39): JSON-RPC 2.0, one message per
+// line. It speaks the 2026-07-28 revision — stateless: no handshake, each request carries
+// `io.modelcontextprotocol/protocolVersion` in `_meta`, `server/discover` advertises versions and
+// capabilities, every result has `resultType`, `tools/list` is cacheable (`ttlMs`, `cacheScope`).
+// Clients on 2025-11-25 still work: `initialize` is answered and a request without the version
+// meta is taken as that revision. Tools only: no resources, prompts, sampling or roots.
+import { TOOLS, callTool } from './tools.js';
+export const LATEST = '2026-07-28';
+export const SUPPORTED = [LATEST, '2025-11-25', '2025-06-18'];
+export const SERVER_INFO = { name: 'sheetpane-mcp', title: 'sheetpane', version: '0.0.0' };
+const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+const ok = (id, result, legacy) => ({ jsonrpc: '2.0', id, result: legacy ? result : { resultType: 'complete', ...result, _meta: { 'io.modelcontextprotocol/serverInfo': SERVER_INFO } } });
+const fail = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+/** Answers one message; a notification (no `id`) gets no answer. */
+export async function handle(msg) {
+    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string')
+        return fail(null, -32600, 'Invalid Request');
+    const req = msg;
+    if (req.id === undefined)
+        return undefined; // notifications (e.g. notifications/initialized): nothing to say
+    const id = req.id;
+    // the revision: from the request's _meta (2026-07-28), else an older client
+    const asked = req.params?._meta?.['io.modelcontextprotocol/protocolVersion'];
+    const legacy = asked === undefined || asked !== LATEST;
+    if (typeof asked === 'string' && !SUPPORTED.includes(asked)) {
+        return fail(id, UNSUPPORTED_PROTOCOL_VERSION, `Unsupported protocol version ${asked}`, { supported: [...SUPPORTED], requested: asked });
+    }
+    const capabilities = { tools: { listChanged: false } };
+    switch (req.method) {
+        case 'server/discover':
+            return ok(id, { supportedVersions: [...SUPPORTED], capabilities, ttlMs: 3_600_000, cacheScope: 'public' }, false);
+        case 'initialize': { // 2025 clients
+            const want = String(req.params?.protocolVersion ?? '2025-11-25');
+            const version = SUPPORTED.includes(want) && want !== LATEST ? want : '2025-11-25';
+            return ok(id, { protocolVersion: version, capabilities, serverInfo: SERVER_INFO, instructions: 'sheetpane tools: describe its API, inspect a workbook, draft or check a rules file, explain an SP code, find the right skill. Read-only.' }, true);
+        }
+        case 'ping':
+            return ok(id, {}, legacy);
+        case 'tools/list':
+            return ok(id, { tools: TOOLS.map(({ name, title, description, inputSchema }) => ({ name, title, description, inputSchema })), ...(legacy ? {} : { ttlMs: 3_600_000, cacheScope: 'public' }) }, legacy);
+        case 'tools/call': {
+            const p = req.params;
+            if (typeof p?.name !== 'string' || !TOOLS.some((t) => t.name === p.name))
+                return fail(id, -32602, `Unknown tool: ${String(p?.name)}`);
+            const r = await callTool(p.name, p.arguments ?? {});
+            return ok(id, r, legacy);
+        }
+        default:
+            return fail(id, -32601, `Method not found: ${req.method}`);
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,36 @@
+import { type ImportedSheet, type ImportedWorkbook } from '@sheetpane/import';
+/** A tool as `tools/list` shows it, plus the function that answers it. */
+export interface Tool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    run: (args: Record<string, unknown>) => Promise<string>;
+}
+/** What `tools/call` returns: text content, and `isError` for a tool error. */
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/** Reads a workbook from a path the agent gives — `.xlsx` or `.csv`, nothing else (SR-LAW-3). */
+export declare function loadWorkbook(path: string): Promise<ImportedWorkbook>;
+/** The header row guess: the first of the top ten rows whose filled cells are all text, two or more of them, with a row below it. */
+export declare function guessHeaderRow(s: ImportedSheet): number;
+/** Sheets, sizes, header-row guess, titles, column types, merges and the plugins it would use. */
+export declare function inspectWorkbook(path: string): Promise<Record<string, unknown>>;
+/** A rules file drafted from a sheet's headers and inferred types — always a draft to review. */
+export declare function draftRules(path: string, sheet?: string): Promise<Record<string, unknown>>;
+/** A rules file checked the way the grid checks it, and against a workbook when one is given. */
+export declare function checkRules(json: unknown, path?: string): Promise<Record<string, unknown>>;
+/** The docs entry for an SP code: title, severity, meaning, likely cause, fix and link. */
+export declare function explainCode(code: string): Record<string, unknown>;
+/** The skills whose names and descriptions share the most words with the task — no model. */
+export declare function findSkill(task: string): Record<string, unknown>;
+/** The tools, in the order `tools/list` gives them. */
+export declare const TOOLS: Tool[];
+/** Runs one tool. A ToolError or a failed read is the tool's error, never the server's. */
+export declare function callTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AASA,OAAO,EAAyB,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrG,0EAA0E;AAC1E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACzD;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IAAG,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE;AAmB5F,iGAAiG;AACjG,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAY1E;AAyBD,qIAAqI;AACrI,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAQvD;AA2CD,kGAAkG;AAClG,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8BpF;AAID,iGAAiG;AACjG,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA6B/F;AAED,iGAAiG;AACjG,wBAAsB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoC/F;AAYD,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBjE;AAoBD,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB/D;AAMD,uDAAuD;AACvD,eAAO,MAAM,KAAK,EAAE,IAAI,EA8CvB,CAAC;AAEF,2FAA2F;AAC3F,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAO/F"}

package/dist/tools.js

@@ -0,0 +1,413 @@
+// The tools (W-39). Each is deterministic — the same input gives the same output — and computed
+// from what ships: the import package, the grid's rules checker, docs/ERRORS.md, the skills and
+// the custom-elements manifest. Read-only: paths come from the agent, nothing is written, no
+// network. A bad input is a tool error (`isError: true`), never a crash.
+import { readFile, stat } from 'node:fs/promises';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { read, BUILTIN_FORMATS } from '@sheetpane/import';
+import { checkDocument, describeRule, CODES, codeUrl, spMessage } from '@sheetpane/grid';
+import { describeApi } from './api.js';
+const here = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+/** A tool error: its coded message goes back to the agent, and the server keeps running. */
+class ToolError extends Error {
+    spCode;
+    constructor(spCode, detail) {
+        super(spMessage(spCode, detail));
+        this.spCode = spCode;
+    }
+}
+const SCHEMA = 'https://json-schema.org/draft/2020-12/schema';
+const MAX_BYTES = 256 * 1024 * 1024;
+const str = (args, k, required = true) => {
+    const v = args[k];
+    if (v === undefined && !required)
+        return undefined;
+    if (typeof v !== 'string' || !v.trim())
+        throw new ToolError('SP-7001', `“${k}” must be a non-empty string`);
+    return v;
+};
+// ── workbooks ──────────────────────────────────────────────────────────────
+/** Reads a workbook from a path the agent gives — `.xlsx` or `.csv`, nothing else (SR-LAW-3). */
+export async function loadWorkbook(path) {
+    const abs = resolve(path);
+    let size;
+    try {
+        size = (await stat(abs)).size;
+    }
+    catch {
+        throw new ToolError('SP-7002', `No file at ${abs}`);
+    }
+    if (size > MAX_BYTES)
+        throw new ToolError('SP-7003', `${abs} is ${size} bytes — past the 256 MB this tool reads`);
+    const bytes = new Uint8Array(await readFile(abs));
+    try {
+        return await read(bytes, { name: abs.split(/[\\/]/).pop() });
+    }
+    catch (e) {
+        // the reader's refusal keeps its own code (SP-10xx); anything else is this tool's SP-7004
+        const err = e;
+        if (err.spCode)
+            throw new ToolError(err.spCode, err.spDetail ?? err.message);
+        throw new ToolError('SP-7004', `${abs}: ${err.message}`);
+    }
+}
+const DATE_CODE = /[dmyhs]/i;
+function isDateCode(code) {
+    if (!code || code === 'General')
+        return false;
+    const bare = code.replace(/"[^"]*"/g, '').replace(/\\./g, '').replace(/\[[^\]]*\]/g, '').replace(/_./g, '').replace(/\*./g, '');
+    return DATE_CODE.test(bare);
+}
+const a1 = (r, c) => { let s = '', n = c + 1; while (n) {
+    const m = (n - 1) % 26;
+    s = String.fromCharCode(65 + m) + s;
+    n = (n - 1 - m) / 26;
+} return `${s}${r + 1}`; };
+function kindOf(wb, s, r, c) {
+    const v = s.rows[r]?.[c];
+    if (v === null || v === undefined || v === '')
+        return 'empty';
+    if (typeof v === 'boolean')
+        return 'boolean';
+    if (typeof v === 'string')
+        return 'text';
+    const xf = s.styleIndex[a1(r, c)];
+    if (xf !== undefined) {
+        const id = wb.styles.cellXfs[xf]?.numFmtId ?? 0;
+        if (isDateCode(wb.styles.numFmts[id] ?? BUILTIN_FORMATS[id]))
+            return 'date';
+    }
+    return Number.isInteger(v) ? 'integer' : 'number';
+}
+/** The header row guess: the first of the top ten rows whose filled cells are all text, two or more of them, with a row below it. */
+export function guessHeaderRow(s) {
+    const top = Math.min(10, s.rows.length - 1);
+    for (let r = 0; r < top; r++) {
+        const row = s.rows[r] ?? [];
+        const filled = row.filter((v) => v !== null && v !== undefined && v !== '');
+        if (filled.length >= 2 && filled.every((v) => typeof v === 'string'))
+            return r + 1;
+    }
+    return 1;
+}
+/** One column below the header row: its title, inferred type, blanks, and up to 12 distinct values. */
+function columnInfo(wb, s, headerRow, c) {
+    const title = (s.text[headerRow - 1]?.[c] ?? String(s.rows[headerRow - 1]?.[c] ?? '')).trim();
+    const kinds = new Set();
+    const seen = new Set();
+    let blanks = 0;
+    for (let r = headerRow; r < s.rows.length; r++) {
+        const k = kindOf(wb, s, r, c);
+        if (k === 'empty') {
+            blanks++;
+            continue;
+        }
+        kinds.add(k);
+        if (seen.size <= 12)
+            seen.add(s.text[r]?.[c] ?? String(s.rows[r]?.[c]));
+    }
+    if (kinds.has('integer') && kinds.has('number'))
+        kinds.delete('integer');
+    const type = kinds.size === 0 ? 'empty' : kinds.size === 1 ? [...kinds][0] : 'mixed';
+    return { column: a1(0, c).replace(/\d+$/, ''), title, type, blanks, distinct: seen.size > 12 ? 13 : seen.size, ...(seen.size <= 12 ? { values: [...seen].sort() } : {}) };
+}
+/** The plugins a workbook would use: the feature is in the file, so the plugin shows it. */
+function pluginsFor(wb) {
+    const out = new Set();
+    const ids = new Set();
+    for (const s of wb.sheets)
+        for (const xf of Object.values(s.styleIndex))
+            ids.add(xf);
+    for (const xf of ids) {
+        const x = wb.styles.cellXfs[xf];
+        if (!x)
+            continue;
+        if (x.numFmtId !== 0)
+            out.add('numfmt');
+        if (x.fontId !== 0 || x.fillId !== 0 || x.borderId !== 0 || x.alignment)
+            out.add('styles');
+    }
+    for (const s of wb.sheets) {
+        if (Object.keys(s.formulas).length)
+            out.add('formulas');
+        if (s.dataValidations.length)
+            out.add('validation');
+        if (s.conditionalFormats.length)
+            out.add('condfmt');
+        if (s.drawings.some((d) => d.kind === 'picture'))
+            out.add('images');
+        if (s.drawings.some((d) => d.kind === 'chart'))
+            out.add('charts');
+        if (s.notes.length || s.threadedComments.length)
+            out.add('comments');
+    }
+    return [...out].sort().map((p) => `@sheetpane/${p}`);
+}
+/** Sheets, sizes, header-row guess, titles, column types, merges and the plugins it would use. */
+export async function inspectWorkbook(path) {
+    const wb = await loadWorkbook(path);
+    return {
+        file: path,
+        format: wb.source,
+        ...(wb.delimiter ? { delimiter: wb.delimiter } : {}),
+        activeSheet: wb.sheets[wb.activeSheet]?.name,
+        plugins: pluginsFor(wb),
+        sheets: wb.sheets.map((s) => {
+            const cols = s.rows.reduce((m, r) => Math.max(m, r.length), 0);
+            const headerRow = guessHeaderRow(s);
+            return {
+                name: s.name,
+                ...(s.hidden ? { hidden: true } : {}),
+                rows: s.rows.length,
+                columns: cols,
+                ...(s.rows.length && cols ? { dimension: `A1:${a1(s.rows.length - 1, cols - 1)}` } : {}),
+                headerRow,
+                columnsInfo: Array.from({ length: cols }, (_, c) => columnInfo(wb, s, headerRow, c)),
+                merges: s.merges ?? [],
+                ...(s.freeze.rows || s.freeze.cols ? { freeze: s.freeze } : {}),
+                formulas: Object.keys(s.formulas).length,
+                dataValidations: s.dataValidations.length,
+                conditionalFormats: s.conditionalFormats.length,
+                pictures: s.drawings.filter((d) => d.kind === 'picture').length,
+                charts: s.drawings.filter((d) => d.kind === 'chart').length,
+                notes: s.notes.length + s.threadedComments.length,
+            };
+        }),
+    };
+}
+// ── rules files (W-33) ─────────────────────────────────────────────────────
+/** A rules file drafted from a sheet's headers and inferred types — always a draft to review. */
+export async function draftRules(path, sheet) {
+    const wb = await loadWorkbook(path);
+    const pick = sheet === undefined ? wb.sheets : wb.sheets.filter((s) => s.name === sheet);
+    if (!pick.length)
+        throw new ToolError('SP-7005', `No sheet is named “${sheet}” — the sheets are ${wb.sheets.map((s) => `“${s.name}”`).join(', ')}`);
+    const sheets = {};
+    const notes = [];
+    for (const s of pick) {
+        const headerRow = guessHeaderRow(s);
+        const cols = s.rows.reduce((m, r) => Math.max(m, r.length), 0);
+        const columns = {};
+        for (let c = 0; c < cols; c++) {
+            const info = columnInfo(wb, s, headerRow, c);
+            if (!info.title) {
+                if (info.type !== 'empty')
+                    notes.push(`“${s.name}” column ${info.column} has no title in row ${headerRow} — no rule drafted`);
+                continue;
+            }
+            if (columns[info.title]) {
+                notes.push(`“${s.name}” has two columns titled “${info.title}” — only the first gets a rule`);
+                continue;
+            }
+            const r = {};
+            if (info.blanks === 0 && info.type !== 'empty')
+                r.required = true;
+            if (info.type !== 'empty' && info.type !== 'mixed')
+                r.type = info.type;
+            if (info.type === 'text' && info.values && info.values.length >= 2 && info.values.length <= 12 && s.rows.length - headerRow > info.values.length)
+                r.oneOf = info.values;
+            if (info.type === 'mixed')
+                notes.push(`“${s.name}” column “${info.title}” mixes types — no type drafted`);
+            columns[info.title] = r;
+        }
+        sheets[s.name] = { ...(headerRow !== 1 ? { headerRow } : {}), columns };
+    }
+    return {
+        draft: true,
+        note: 'A draft from the file as it is — review every rule before using it: a column with no blanks today may allow them, and oneOf lists only the values seen.',
+        rules: { $schema: 'https://unpkg.com/@sheetpane/grid/rules.schema.json', version: 1, sheets },
+        ...(notes.length ? { notes } : {}),
+    };
+}
+/** A rules file checked the way the grid checks it, and against a workbook when one is given. */
+export async function checkRules(json, path) {
+    let doc = json;
+    if (typeof json === 'string') {
+        try {
+            doc = JSON.parse(json);
+        }
+        catch (e) {
+            return { ok: false, problems: [{ code: 'SP-6011', message: `The rules file is not JSON — ${e.message}` }] };
+        }
+    }
+    const { sheets, problems } = checkDocument(doc);
+    const out = problems.map((p) => ({ ...p }));
+    const rules = [];
+    for (const [name, d] of sheets) {
+        for (const [title, r] of Object.entries(d.columns))
+            rules.push({ sheet: name, target: `column “${title}”`, rule: describeRule(r) });
+        for (const [ref, r] of Object.entries(d.cells))
+            rules.push({ sheet: name, target: `cell ${ref}`, rule: describeRule(r) });
+    }
+    if (path !== undefined) {
+        const wb = await loadWorkbook(path);
+        const star = sheets.get('*');
+        const headerRowOf = (name) => sheets.get(name)?.headerRow ?? star?.headerRow ?? 1;
+        const found = new Map();
+        for (const s of wb.sheets) {
+            const hr = headerRowOf(s.name), seen = new Set();
+            for (const [c, t] of (s.text[hr - 1] ?? []).entries()) {
+                const k = t.trim().toLowerCase();
+                if (!k)
+                    continue;
+                if (seen.has(k)) {
+                    out.push({ code: 'SP-6024', sheet: s.name, found: t.trim(), message: `Two columns are titled “${t.trim()}” in “${s.name}” — the rules check column ${a1(0, c).replace(/\d+$/, '')}'s first match only` });
+                    continue;
+                }
+                seen.add(k);
+                if (!found.has(k))
+                    found.set(k, new Set());
+                found.get(k).add(s.name);
+            }
+        }
+        for (const name of sheets.keys())
+            if (name !== '*' && !wb.sheets.some((s) => s.name === name))
+                out.push({ code: 'SP-6022', sheet: name, found: name, message: `No sheet is named “${name}” — its rules are not checked` });
+        for (const title of Object.keys(star?.columns ?? {}))
+            if (!found.has(title.trim().toLowerCase()))
+                out.push({ code: 'SP-6023', sheet: '*', found: title, message: `No column is titled “${title}” in any sheet — its rule is not checked` });
+        for (const [name, d] of sheets) {
+            if (name === '*' || !wb.sheets.some((s) => s.name === name))
+                continue;
+            for (const title of Object.keys(d.columns))
+                if (!found.get(title.trim().toLowerCase())?.has(name))
+                    out.push({ code: 'SP-6023', sheet: name, found: title, message: `No column is titled “${title}” in row ${headerRowOf(name)} of “${name}” — its rule is not checked` });
+        }
+    }
+    return { ok: out.length === 0, problems: out.map((p) => ({ ...p, url: codeUrl(p.code) })), rules };
+}
+// ── error codes (W-40) ─────────────────────────────────────────────────────
+let errorsDoc;
+/** docs/ERRORS.md as shipped in this package's dist (copied at build), else the repo's. */
+function errorsText() {
+    if (errorsDoc !== undefined)
+        return errorsDoc;
+    for (const p of [join(here, 'ERRORS.md'), join(here, '../../../docs/ERRORS.md')])
+        if (existsSync(p))
+            return (errorsDoc = readFileSync(p, 'utf8'));
+    throw new ToolError('SP-7007', 'docs/ERRORS.md is missing from this install');
+}
+/** The docs entry for an SP code: title, severity, meaning, likely cause, fix and link. */
+export function explainCode(code) {
+    const c = code.trim().toUpperCase().replace(/^SP(\d)/, 'SP-$1');
+    if (!(c in CODES)) {
+        const near = Object.keys(CODES).filter((k) => k.slice(0, 5) === c.slice(0, 5)).slice(0, 8);
+        throw new ToolError('SP-7006', `${code} is not a sheetpane code. Codes look like SP-1001${near.length ? `; nearby: ${near.join(', ')}` : ''}`);
+    }
+    const info = CODES[c];
+    const text = errorsText();
+    const start = text.indexOf(`\n### ${c}\n`);
+    const body = start < 0 ? '' : text.slice(start + 1, text.indexOf('\n### ', start + 5) < 0 ? text.indexOf('\n---', start) : Math.min(...[text.indexOf('\n### ', start + 5), text.indexOf('\n---', start)].filter((i) => i > 0)));
+    const field = (label) => new RegExp(String.raw `- \*\*${label}:\*\* (.*)`).exec(body)?.[1]?.trim();
+    return {
+        code: c,
+        title: info.title,
+        severity: info.severity,
+        ...(info.retired ? { retired: true } : {}),
+        meaning: field('Meaning'),
+        cause: field('Likely cause'),
+        fix: field('Fix'),
+        url: codeUrl(c),
+    };
+}
+let skillList;
+function skills() {
+    if (skillList)
+        return skillList;
+    const root = join(dirname(require.resolve('@sheetpane/skills/package.json')), 'skills');
+    skillList = readdirSync(root).sort().map((name) => {
+        const text = readFileSync(join(root, name, 'SKILL.md'), 'utf8');
+        const description = /^description:\s*(.*)$/m.exec(text)?.[1]?.replace(/^["']|["']$/g, '').trim() ?? '';
+        return { name, description, path: `node_modules/@sheetpane/skills/skills/${name}/SKILL.md` };
+    });
+    return skillList;
+}
+const STOP = new Set(['a', 'an', 'the', 'to', 'of', 'in', 'on', 'for', 'and', 'or', 'with', 'how', 'do', 'i', 'my', 'is', 'it', 'use', 'using', 'sheetpane', 'not', 'when', 'what', 'into', 'from', 'this', 'that', 'want', 'need', 'can']);
+const words = (s) => s.toLowerCase().split(/[^a-z0-9.]+/).filter((w) => w.length > 1 && !STOP.has(w)).map((w) => w.replace(/(ing|es|s)$/, ''));
+/** The skills whose names and descriptions share the most words with the task — no model. */
+export function findSkill(task) {
+    const want = new Set(words(task));
+    if (!want.size)
+        throw new ToolError('SP-7001', 'Describe the task in a few words, e.g. "validate columns from a JSON file"');
+    const scored = skills().map((s) => {
+        // a "Not for…" clause names what the skill is not for: its words do not count
+        const own = s.description.split(/\bNot\b/)[0];
+        const hay = words(`${s.name.replace(/^sheetpane-?/, '')} ${own}`);
+        const nameWords = new Set(words(s.name.replace(/^sheetpane-?/, '').replace(/-/g, ' ')));
+        let score = 0;
+        for (const w of new Set(hay))
+            if (want.has(w))
+                score += nameWords.has(w) ? 3 : 1;
+        return { ...s, score };
+    }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    const best = scored.slice(0, 3);
+    return best.length
+        ? { matches: best.map(({ name, description, path, score }) => ({ name, path, description, score })) }
+        : { matches: [], hint: 'No skill matched. Start with the "sheetpane" skill — it routes to the rest.', start: skills().find((s) => s.name === 'sheetpane')?.path };
+}
+// ── the list ───────────────────────────────────────────────────────────────
+const pathProp = { type: 'string', description: 'Path to an .xlsx or .csv file, absolute or relative to where the server runs.' };
+/** The tools, in the order `tools/list` gives them. */
+export const TOOLS = [
+    {
+        name: 'describe_api',
+        title: 'Describe sheetpane API',
+        description: 'Look up one name of sheetpane\'s public API — an element (sheetpane-excel), attribute, property, method, event (sheetpane-change), CSS custom property (--sp-*), slot, CSS part or plugin — and get its entry from the custom-elements manifest, its TSDoc and the record that specifies it. Use this before writing an attribute or event name instead of guessing.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { name: { type: 'string', description: 'The name to look up, e.g. "flagging", "sheetpane-export", "--sp-accent", "exportFile", "@sheetpane/charts".' } }, required: ['name'], additionalProperties: false },
+        run: async (a) => JSON.stringify(describeApi(str(a, 'name')), null, 2),
+    },
+    {
+        name: 'inspect_workbook',
+        title: 'Inspect a workbook',
+        description: 'Read an .xlsx or .csv file and report its sheets, sizes, header-row guess, column titles, inferred column types (text, number, integer, date, boolean, mixed), blanks, distinct values, merges, and which @sheetpane plugins the file would use. Read-only.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { path: pathProp }, required: ['path'], additionalProperties: false },
+        run: async (a) => JSON.stringify(await inspectWorkbook(str(a, 'path')), null, 2),
+    },
+    {
+        name: 'draft_rules',
+        title: 'Draft a rules file',
+        description: 'Draft a sheetpane rules file (the JSON <sheetpane-excel rules-src> loads) from a workbook: one rule per titled column — required where the column has no blanks, its inferred type, and oneOf for a text column with 2–12 distinct values. Always a draft for a person to review.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { path: pathProp, sheet: { type: 'string', description: 'Only this sheet; every sheet when omitted.' } }, required: ['path'], additionalProperties: false },
+        run: async (a) => JSON.stringify(await draftRules(str(a, 'path'), str(a, 'sheet', false)), null, 2),
+    },
+    {
+        name: 'check_rules',
+        title: 'Check a rules file',
+        description: 'Check a sheetpane rules file exactly as the grid does (unknown keys and rule words, bad types, patterns, ranges, version), and list each rule in words. With a workbook path, also list the sheets and column titles the rules name that the workbook lacks.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { rules: { description: 'The rules file: its JSON text, or the parsed object.', type: ['string', 'object'] }, path: pathProp }, required: ['rules'], additionalProperties: false },
+        run: async (a) => {
+            if (a.rules === undefined)
+                throw new ToolError('SP-7001', '“rules” is required: the rules file\'s JSON text or object');
+            return JSON.stringify(await checkRules(a.rules, str(a, 'path', false)), null, 2);
+        },
+    },
+    {
+        name: 'explain_code',
+        title: 'Explain an SP code',
+        description: 'Explain a sheetpane error code (SP-1001 … SP-6025) from its docs entry: title, severity, meaning, likely cause, fix and the link to the docs.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { code: { type: 'string', description: 'The code, e.g. "SP-1002".', pattern: '^[Ss][Pp]-?\\d{4}$' } }, required: ['code'], additionalProperties: false },
+        run: async (a) => JSON.stringify(explainCode(str(a, 'code')), null, 2),
+    },
+    {
+        name: 'find_skill',
+        title: 'Find the sheetpane skill',
+        description: 'Name the sheetpane agent skill for a task (embedding, React, column rules, a rules file, theming, testing, plugins…) by matching its words against the skills\' names and descriptions. Returns up to three, best first, with the SKILL.md path to read.',
+        inputSchema: { $schema: SCHEMA, type: 'object', properties: { task: { type: 'string', description: 'The task in a few words.' } }, required: ['task'], additionalProperties: false },
+        run: async (a) => JSON.stringify(findSkill(str(a, 'task')), null, 2),
+    },
+];
+/** Runs one tool. A ToolError or a failed read is the tool's error, never the server's. */
+export async function callTool(name, args) {
+    const tool = TOOLS.find((t) => t.name === name);
+    try {
+        return { content: [{ type: 'text', text: await tool.run(args ?? {}) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: e instanceof ToolError ? e.message : `${name} failed: ${e.message}` }], isError: true };
+    }
+}
+//# sourceMappingURL=tools.js.map