@components-kit/open-workbook 0.1.1 → 0.1.3

package/assets/instructions/open-workbook-excel/references/workflows.md

@@ -64,12 +64,15 @@ Cleaning writes must stay within the requested sheet, range, table, or registere
 ## Update Tables, Filters, Or Sorts
 
 1. Inspect with `excel.table.get_info` and `excel.filter.get_filters`.
-2. Use `excel.table.append_rows` or `excel.table.update_rows` for data.
-3. Use `excel.table.resize` only when structure must change.
-4. Preserve or reapply filters with `excel.filter.apply`, `excel.filter.preserve_from_template`, or `excel.table.preserve_filters`.
-5. Validate with `excel.validate.tables` and `excel.validate.filters`.
+2. Use projected `excel.table.read` options when only some columns or rows are needed.
+3. Use `excel.table.reorder_columns` for column order changes.
+4. Use `excel.table.append_rows` or `excel.table.update_rows` for data.
+5. Use `excel.table.resize` only when structure must change.
+6. Preserve or reapply filters with `excel.filter.apply`, `excel.filter.preserve_from_template`, or `excel.table.preserve_filters`.
+7. Validate with `excel.validate.tables` and `excel.validate.filters`.
 
 Avoid raw range writes inside table bodies when table tools can express the intent.
+Avoid full-table rewrites for layout changes such as column reorder; they are slow on large tables and can break table identity or dependent objects.
 
 ## Create Or Update Pivots And Charts
 

package/assets/mcp-server/dist/index.js

@@ -45,9 +45,10 @@ const STYLE_COPY_TOOL_DIMENSIONS = {
     "excel.style.copy_hidden_rows_columns": "hiddenRowsColumns"
 };
 const runtime = await createRuntimeFacade();
+const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.3";
 const server = new McpServer({
     name: "open-workbook",
-    version: "0.1.1"
+    version: runtimeVersion
 });
 registerRuntimeTools(server);
 registerWorkbookTools(server);
@@ -974,14 +975,14 @@ function registerRangeTools(mcp) {
     ]) {
         registerMcpTool(mcp, name, {
             title: name.replace(/^excel\./, "").replace(/\./g, " "),
-            description: "Read a range facet using the full range snapshot path.",
+            description: "Read one range facet without loading unrelated cell payloads.",
             inputSchema: readSchema,
             annotations: {
                 readOnlyHint: true,
                 destructiveHint: false,
                 openWorldHint: false
             }
-        }, async ({ workbookId, sheetName, address }) => jsonResult(await readRangeSnapshot(workbookId, sheetName, address)));
+        }, async ({ workbookId, sheetName, address }) => jsonResult(await readRangeSnapshot(workbookId, sheetName, address, rangeReadFacets(name))));
     }
     for (const [name, method] of [
         ["excel.range.read_hyperlinks", "range.read_hyperlinks"],
@@ -1951,10 +1952,19 @@ function registerTableTools(mcp) {
     }, async (args) => jsonResult(await runtime.getTableInfo(tableSelector(args))));
     registerMcpTool(mcp, "excel.table.read", {
         title: "Read Excel table",
-        description: "Read table headers, values, formulas, text, number formats, and metadata.",
-        inputSchema: tableSelectorSchema(),
+        description: "Read table headers, selected data facets, optional columns, optional row page, and metadata.",
+        inputSchema: {
+            ...tableSelectorSchema(),
+            includeValues: z.boolean().optional(),
+            includeFormulas: z.boolean().optional(),
+            includeText: z.boolean().optional(),
+            includeNumberFormats: z.boolean().optional(),
+            columns: z.array(z.union([z.string(), z.number().int().min(0)])).optional(),
+            rowOffset: z.number().int().min(0).optional(),
+            rowLimit: z.number().int().min(0).optional()
+        },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
-    }, async (args) => jsonResult(await runtime.readTable(tableSelector(args))));
+    }, async (args) => jsonResult(await runtime.readTable(tableReadRequest(args))));
     registerMcpTool(mcp, "excel.table.create", {
         title: "Create Excel table",
         description: "Create a structured table from a range, optionally writing values first.",
@@ -1976,6 +1986,18 @@ function registerTableTools(mcp) {
         inputSchema: { ...tableSelectorSchema(), address: z.string() },
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.resizeTable({ ...tableSelector(args), address: args.address })));
+    registerMcpTool(mcp, "excel.table.reorder_columns", {
+        title: "Reorder Excel table columns",
+        description: "Reorder columns in an existing structured table without clearing or recreating the table.",
+        inputSchema: {
+            ...tableSelectorSchema(),
+            columnOrder: z.array(z.union([z.string(), z.number().int().min(0)]))
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false }
+    }, async (args) => jsonResult(await runtime.reorderTableColumns({
+        ...tableSelector(args),
+        columnOrder: args.columnOrder
+    })));
     registerMcpTool(mcp, "excel.table.append_rows", {
         title: "Append Excel table rows",
         description: "Append one or more rows to a structured table.",
@@ -3251,7 +3273,23 @@ function registerEventTools(mcp) {
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     }, async ({ debounceMs }) => jsonResult(runtime.setEventDebounce(debounceMs)));
 }
-async function readRangeSnapshot(workbookId, sheetName, address) {
+function rangeReadFacets(toolName) {
+    switch (toolName) {
+        case "excel.range.read_values":
+            return ["values"];
+        case "excel.range.read_formulas":
+            return ["formulas"];
+        case "excel.range.read_number_formats":
+            return ["numberFormat"];
+        case "excel.range.read_display_text":
+            return ["text"];
+        case "excel.range.read_styles":
+            return ["style"];
+        default:
+            return ["values", "formulas", "numberFormat", "text", "style"];
+    }
+}
+async function readRangeSnapshot(workbookId, sheetName, address, facets) {
     const operation = {
         kind: "range.read_full",
         operationId: makeId("op"),
@@ -3264,6 +3302,9 @@ async function readRangeSnapshot(workbookId, sheetName, address) {
             address
         }
     };
+    if (facets !== undefined) {
+        operation.facets = facets;
+    }
     return runtime.applyBatch({
         workbookId: workbookId,
         mode: "apply",
@@ -3290,6 +3331,31 @@ function tableSelector(args) {
         tableName: args.tableName
     };
 }
+function tableReadRequest(args) {
+    const request = tableSelector(args);
+    if (args.includeValues !== undefined) {
+        request.includeValues = args.includeValues;
+    }
+    if (args.includeFormulas !== undefined) {
+        request.includeFormulas = args.includeFormulas;
+    }
+    if (args.includeText !== undefined) {
+        request.includeText = args.includeText;
+    }
+    if (args.includeNumberFormats !== undefined) {
+        request.includeNumberFormats = args.includeNumberFormats;
+    }
+    if (args.columns !== undefined) {
+        request.columns = args.columns;
+    }
+    if (args.rowOffset !== undefined) {
+        request.rowOffset = args.rowOffset;
+    }
+    if (args.rowLimit !== undefined) {
+        request.rowLimit = args.rowLimit;
+    }
+    return request;
+}
 function tableCreateRequest(args) {
     const request = {
         workbookId: args.workbookId,