@tiwater/office-mcp 0.21.27 → 0.21.28

package/office/contracts/tiwater-office-provider-contract-manifest-v1.json

@@ -2,7 +2,7 @@
   "schema": "tiwater.office-provider-contract-manifest/v1",
   "provider": {
     "id": "@tiwater/office-mcp",
-    "version": "0.21.27"
+    "version": "0.21.28"
   },
   "tools": [
     {
@@ -456,6 +456,17 @@
         "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
       }
     },
+    {
+      "name": "xlsx_read_range",
+      "providerContract": {
+        "source": "packages/xlsx-cli/contracts/mcp-input/xlsx_read_range.schema.json",
+        "sha256": "04b0ce1b912047f774fbbbb6ba7cf55e5e53a9b74d6f027d9c21b4d6d7397225"
+      },
+      "inputContract": {
+        "path": "office/contracts/xlsx_read_range.schema.json",
+        "sha256": "04b0ce1b912047f774fbbbb6ba7cf55e5e53a9b74d6f027d9c21b4d6d7397225"
+      }
+    },
     {
       "name": "xlsx_set_cell_number_format",
       "providerContract": {

package/office/contracts/xlsx_read_range.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/xlsx_read_range/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Current XLSX workbook. Convert legacy XLS before selecting Open XML cells.",
+      "x-tiwater-file-role": "read"
+    },
+    "sheet": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Exact current worksheet name returned by workbook observation."
+    },
+    "range": {
+      "type": "string",
+      "pattern": "^[A-Za-z]{1,3}[1-9][0-9]*(?::[A-Za-z]{1,3}[1-9][0-9]*)?$",
+      "description": "Explicit native A1 cell or rectangular range. A single cell is a one-cell range."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based cell offset in row-major order within the selected range. Continue only when another selected cell is needed."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 256,
+      "description": "Maximum selected cells in this bounded page."
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return this selected technical page directly when it fits the response limit. May be combined with output."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional immutable JSON artifact path for this selected technical page. May be combined with returnContent.",
+      "x-tiwater-file-role": "write"
+    }
+  },
+  "required": ["input", "sheet", "range", "limit", "returnContent"],
+  "additionalProperties": false
+}

package/office/index.mjs

@@ -202,6 +202,67 @@ const xlsxInspectionSummary = z.object({
   }).strict()).max(6),
 }).strict();
 
+const xlsxRangePageSummary = z.object({
+  schema: z.literal('tiwater.xlsx-range-page-receipt/v1'),
+  totalCellCount: z.number().int().nonnegative(),
+  returnedCellCount: z.number().int().nonnegative(),
+  remaining: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative().nullable(),
+}).strict();
+
+const xlsxRangePage = z.object({
+  schema: z.literal('tiwater.xlsx-range-page/v1'),
+  toolVersion: z.string(),
+  file: z.string(),
+  inputSha256: z.string().regex(/^[a-f0-9]{64}$/),
+  sheet: z.string(),
+  range: z.string(),
+  receipt: xlsxRangePageSummary,
+  cells: z.array(z.object({
+    reference: z.string(),
+    row: z.number().int().positive(),
+    column: z.number().int().positive(),
+    physical: z.boolean(),
+    rawValue: z.string().nullable(),
+    formattedValue: z.string().nullable(),
+    valueType: z.string().nullable(),
+    normalizedValue: z.object({ kind: z.string(), iso8601: z.string().nullable() }).strict().nullable(),
+    formula: z.object({
+      text: z.string(),
+      type: z.string().nullable(),
+      sharedIndex: z.number().int().nonnegative().nullable(),
+      reference: z.string().nullable(),
+    }).strict().nullable(),
+    style: z.object({
+      styleIndex: z.number().int().nonnegative(),
+      numberFormatId: z.number().int().nonnegative(),
+      numberFormatCode: z.string().nullable(),
+      fontId: z.number().int().nonnegative(),
+      fillId: z.number().int().nonnegative(),
+      borderId: z.number().int().nonnegative(),
+      horizontalAlignment: z.string().nullable(),
+      verticalAlignment: z.string().nullable(),
+      wrapText: z.boolean(),
+      bold: z.boolean(),
+    }).strict().nullable(),
+    richTextRuns: z.array(z.object({
+      text: z.string(),
+      fontName: z.string().nullable(),
+      color: z.string().nullable(),
+      underline: z.string().nullable(),
+      bold: z.boolean(),
+      italic: z.boolean(),
+    }).strict()).nullable(),
+    mergedRange: z.string().nullable(),
+    mergeOwner: z.string().nullable(),
+  }).strict()).max(256),
+}).strict();
+
+const xlsxRangeReadOutput = largeResultOutput('xlsx_read_range').extend({
+  summary: xlsxRangePageSummary,
+  content: xlsxRangePage.optional(),
+}).strict();
+
 const pptxInspectionSummary = z.object({
   slideCount: z.number().int().nonnegative(),
   masterCount: z.number().int().nonnegative(),
@@ -580,6 +641,14 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true },
     handler: xlsxExportJson,
   },
+  {
+    name: 'xlsx_read_range',
+    description: 'Read one explicit native A1 cell or rectangular range from one current XLSX worksheet. Pages use a row-major cell offset and return physical presence, raw and formatted values, normalized value type, formula metadata, style, rich text, and merged-range ownership. The receipt always reports remaining cells and the next offset. Continue only when another selected cell is needed. Set returnContent true to return the selected page when it fits the response limit. Provide output to store the same complete selected page as an immutable artifact. These channels are independent and may be used together; at least one is required. This tool does not infer regions, headers, records, field meanings, or business mappings; convert legacy XLS before reading Open XML cells.',
+    inputSchema: inputContract('xlsx_read_range'),
+    outputSchema: xlsxRangeReadOutput,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    handler: xlsxReadRange,
+  },
   ...fixedToolDefinitions(xlsxFixedTools),
   {
     name: 'xlsx_validate',
@@ -1202,6 +1271,21 @@ async function xlsxExportJson(args) {
   return deliverLargeJsonResult({ tool: 'xlsx_export_json', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input] });
 }
 
+async function xlsxReadRange(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  return withTempJsonFile(args, async requestPath => {
+    const result = await runJsonCandidateChain(xlsxCandidates, ['xlsx_read_range', requestPath]);
+    return deliverLargeJsonResult({
+      tool: 'xlsx_read_range',
+      args,
+      runtime: commandRuntime(result),
+      payload: result.json,
+      sourcePaths: [input],
+      summary: result.json.receipt,
+    });
+  });
+}
+
 async function xlsxValidate(args) {
   const input = path.resolve(requireString(args.input, 'input'));
   const result = await runJsonCandidateChain(xlsxCandidates, ['validate', input], { allowedExitCodes: [0, 1] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.21.27",
+  "version": "0.21.28",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",