@tiwater/office-mcp 0.18.9 → 0.18.11

package/office/contracts/docx_read_table.schema.json

@@ -17,6 +17,18 @@
       "required": ["part", "path"],
       "additionalProperties": false
     },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "Maximum number of table rows requested in this response page. The provider may return fewer to keep the machine response bounded."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based row offset. Continue from receipt.nextOffset until it is null."
+    },
     "output": {
       "type": "string",
       "minLength": 1,

package/office/contracts/docx_table_index.schema.json

@@ -14,6 +14,18 @@
       "minLength": 1,
       "description": "New JSON artifact path for the complete table index.",
       "x-tiwater-file-role": "write"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000,
+      "description": "Maximum number of table summaries requested in this response page. The provider may return fewer to keep the machine response bounded."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based table offset. Continue from receipt.nextOffset until it is null."
     }
   },
   "required": ["input", "output"],

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.18.9"
+    "version": "0.18.11"
   },
   "tools": [
     {
@@ -130,11 +130,11 @@
       "name": "docx_read_table",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_read_table.schema.json",
-        "sha256": "3b85fb6bc390053abdcdbcf4d5a2a4f958a06154286a0327676144324706af83"
+        "sha256": "c9c2bbab97bd58cb1426418f022f9c78be802eefb509e951fc4efa35e0096b63"
       },
       "inputContract": {
         "path": "office/contracts/docx_read_table.schema.json",
-        "sha256": "3b85fb6bc390053abdcdbcf4d5a2a4f958a06154286a0327676144324706af83"
+        "sha256": "c9c2bbab97bd58cb1426418f022f9c78be802eefb509e951fc4efa35e0096b63"
       }
     },
     {
@@ -207,11 +207,11 @@
       "name": "docx_table_index",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_table_index.schema.json",
-        "sha256": "7549ce28e3cc51ae17cd86c77c97698b6e90f0125afd34ae8831fde7f87ddf67"
+        "sha256": "e10ea5780559f269b6fa193aadb0fc0793009e5e7a4047a7a46aa5621dfeaac1"
       },
       "inputContract": {
         "path": "office/contracts/docx_table_index.schema.json",
-        "sha256": "7549ce28e3cc51ae17cd86c77c97698b6e90f0125afd34ae8831fde7f87ddf67"
+        "sha256": "e10ea5780559f269b6fa193aadb0fc0793009e5e7a4047a7a46aa5621dfeaac1"
       }
     },
     {

package/office/index.mjs

@@ -218,6 +218,13 @@ const docxListObjectsOutput = artifactOutput('docx_list_objects').extend({
 
 const docxTableIndexOutput = artifactOutput('docx_table_index').extend({
   schema: z.literal('tiwater.docx-table-index/v1'),
+  receipt: z.object({
+    schema: z.literal('tiwater.docx-table-index-receipt/v1'),
+    totalCount: z.number().int().nonnegative(),
+    returnedCount: z.number().int().nonnegative(),
+    remaining: z.number().int().nonnegative(),
+    nextOffset: z.number().int().nonnegative().nullable(),
+  }).strict(),
   tables: z.array(z.object({
     address: docxAddress,
     parentAddress: docxAddress.nullable(),
@@ -240,6 +247,15 @@ const docxTableIndexOutput = artifactOutput('docx_table_index').extend({
 
 const docxTableReadOutput = artifactOutput('docx_read_table').extend({
   schema: z.literal('tiwater.docx-table-read/v1'),
+  receipt: z.object({
+    schema: z.literal('tiwater.docx-table-read-receipt/v1'),
+    totalRowCount: z.number().int().nonnegative(),
+    returnedRowCount: z.number().int().nonnegative(),
+    remaining: z.number().int().nonnegative(),
+    nextOffset: z.number().int().nonnegative().nullable(),
+    inlineTextNodesOmitted: z.literal(true),
+    narrowingRequired: z.boolean(),
+  }).strict(),
   address: docxAddress,
   rowCount: z.number().int().nonnegative(),
   columnCount: z.number().int().nonnegative(),
@@ -274,7 +290,14 @@ const docxTableReadOutput = artifactOutput('docx_read_table').extend({
 }).strict();
 
 const docxReadObjectOutput = artifactOutput('docx_read_object').extend({
-  observations: z.array(docxObservationNode).min(1),
+  receipt: z.object({
+    schema: z.literal('tiwater.docx-read-object-receipt/v1'),
+    observationCount: z.number().int().positive(),
+    returnedCount: z.number().int().nonnegative(),
+    responseComplete: z.boolean(),
+    narrowingRequired: z.boolean(),
+  }).strict(),
+  observations: z.array(docxObservationNode),
 }).strict();
 
 const tools = [
@@ -296,7 +319,7 @@ const tools = [
   },
   {
     name: 'docx_table_index',
-    description: 'Locate tables in one current DOCX. Returns one compact index containing every table address, shape, short text preview, and the nearest non-empty paragraph before and after each table. Choose the needed address from this index, then call docx_read_table. It does not return full cell content or decide table semantics.',
+    description: 'Locate tables in one current DOCX. Writes the complete index to output and returns a bounded page containing table address, shape, short text preview, and nearest non-empty paragraphs. Continue with receipt.nextOffset, then call docx_read_table for one selected address. It does not return full cell content or decide table semantics.',
     inputSchema: inputContract('docx_table_index'),
     outputSchema: docxTableIndexOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -304,7 +327,7 @@ const tools = [
   },
   {
     name: 'docx_read_object',
-    description: 'Read selected rows, cells, or paragraphs from one native DOCX in one call and return their requested descendants in address order. Use docx_read_table when the current task needs one complete table. For exact inline content, use an observed cell or paragraph address and request run or text.',
+    description: 'Read selected rows, cells, or paragraphs from one native DOCX and retain the complete result at output. The response returns compact requested descendants when bounded; if receipt.narrowingRequired is true, request fewer observed addresses or descendants. Use docx_read_table for a table.',
     inputSchema: inputContract('docx_read_object'),
     outputSchema: docxReadObjectOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -312,7 +335,7 @@ const tools = [
   },
   {
     name: 'docx_read_table',
-    description: 'Read exactly one table selected from docx_table_index by native OpenXML address. Returns its nearest non-empty paragraph before and after the table, rows, cells, spans, vertical merges, paragraphs, text nodes, and reusable addresses in document order. It does not locate a table or decide business meaning.',
+    description: 'Read exactly one table selected from docx_table_index by native OpenXML address. Writes the complete table, including text nodes, to output and returns a bounded row page with cells, spans, vertical merges, paragraph text, and reusable addresses. Continue with receipt.nextOffset. If receipt.narrowingRequired is true, list rows under the same table and read smaller objects. It does not locate a table or decide business meaning.',
     inputSchema: inputContract('docx_read_table'),
     outputSchema: docxTableReadOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -632,7 +655,74 @@ async function docxObservation(tool, args) {
     if (tool === 'docx_list_objects') {
       return { ...retained, ...payload, objects: payload.objects.map(compactDocxObjectIdentity) };
     }
-    if (tool === 'docx_table_index' || tool === 'docx_read_table') return { ...retained, ...payload };
+    if (tool === 'docx_table_index') {
+      const totalCount = payload.tables.length;
+      const offset = Math.min(args.offset ?? 0, totalCount);
+      const requestedLimit = args.limit ?? totalCount;
+      const tables = [];
+      for (const table of payload.tables.slice(offset, offset + requestedLimit)) {
+        const candidate = [...tables, table];
+        if (tables.length > 0 && Buffer.byteLength(JSON.stringify(candidate)) > 7_000) break;
+        tables.push(table);
+      }
+      const nextOffset = offset + tables.length < totalCount ? offset + tables.length : null;
+      return {
+        ...retained,
+        schema: payload.schema,
+        receipt: {
+          schema: 'tiwater.docx-table-index-receipt/v1',
+          totalCount,
+          returnedCount: tables.length,
+          remaining: totalCount - offset - tables.length,
+          nextOffset,
+        },
+        tables,
+      };
+    }
+    if (tool === 'docx_read_table') {
+      const totalRowCount = payload.rows.length;
+      const offset = Math.min(args.offset ?? 0, totalRowCount);
+      const requestedLimit = args.limit ?? totalRowCount;
+      const rows = [];
+      let narrowingRequired = false;
+      for (const sourceRow of payload.rows.slice(offset, offset + requestedLimit)) {
+        const row = {
+          ...sourceRow,
+          cells: sourceRow.cells.map(cell => ({
+            ...cell,
+            paragraphs: cell.paragraphs.map(paragraph => ({ ...paragraph, textNodes: [] })),
+          })),
+        };
+        const candidate = [...rows, row];
+        if (Buffer.byteLength(JSON.stringify(candidate)) > 6_500) {
+          narrowingRequired = rows.length === 0;
+          break;
+        }
+        rows.push(row);
+      }
+      const nextOffset = !narrowingRequired && offset + rows.length < totalRowCount
+        ? offset + rows.length
+        : null;
+      return {
+        ...retained,
+        schema: payload.schema,
+        address: payload.address,
+        rowCount: payload.rowCount,
+        columnCount: payload.columnCount,
+        precedingParagraph: payload.precedingParagraph,
+        followingParagraph: payload.followingParagraph,
+        receipt: {
+          schema: 'tiwater.docx-table-read-receipt/v1',
+          totalRowCount,
+          returnedRowCount: rows.length,
+          remaining: totalRowCount - offset - rows.length,
+          nextOffset,
+          inlineTextNodesOmitted: true,
+          narrowingRequired,
+        },
+        rows,
+      };
+    }
     throw new Error(`unsupported-docx-observation-tool:${tool}`);
   });
 }
@@ -643,12 +733,21 @@ async function docxReadObject(args) {
   const { output: _output, ...request } = args;
   return withTempJsonFile(request, async requestPath => {
     const result = await runJsonCandidateChain(docxCandidates, ['docx_read_object', requestPath]);
+    const observations = result.json.observations.map(compactDocxObservation);
+    const responseComplete = Buffer.byteLength(JSON.stringify(observations)) <= 6_500;
     return {
       tool: 'docx_read_object',
       runtime: commandRuntime(result),
       source: await fileArtifact(input),
       artifact: await writeJsonArtifact(output, result.json),
-      observations: result.json.observations.map(compactDocxObservation),
+      receipt: {
+        schema: 'tiwater.docx-read-object-receipt/v1',
+        observationCount: observations.length,
+        returnedCount: responseComplete ? observations.length : 0,
+        responseComplete,
+        narrowingRequired: !responseComplete,
+      },
+      observations: responseComplete ? observations : [],
     };
   });
 }

package/package.json

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