@tiwater/office-mcp 0.18.10 → 0.18.12

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/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.10"
+    "version": "0.18.12"
   },
   "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"
       }
     },
     {

package/office/index.mjs

@@ -247,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(),
@@ -281,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 = [
@@ -295,7 +311,7 @@ const tools = [
   },
   {
     name: 'docx_list_objects',
-    description: 'Page through mixed nearest-child OpenXML objects when document order or paragraph relationships are required. Continue with nextOffset and descend through a returned parent address. Do not use this tool to locate tables or read a whole document: use docx_table_index to locate tables, then docx_read_table for one selected table.',
+    description: 'Page through mixed nearest-child OpenXML objects when document order or paragraph relationships are required. The complete requested provider page is retained at output; the response returns a byte-bounded prefix. Continue with receipt.nextOffset and descend through a returned parent address. Do not use this tool to locate tables or read a whole document: use docx_table_index to locate tables, then docx_read_table for one selected table.',
     inputSchema: inputContract('docx_list_objects'),
     outputSchema: docxListObjectsOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -311,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 },
@@ -319,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 },
@@ -637,7 +653,28 @@ async function docxObservation(tool, args) {
       artifact: await writeJsonArtifact(output, result.json),
     };
     if (tool === 'docx_list_objects') {
-      return { ...retained, ...payload, objects: payload.objects.map(compactDocxObjectIdentity) };
+      const totalCount = payload.receipt.totalCount;
+      const offset = Math.min(args.offset ?? 0, totalCount);
+      const objects = [];
+      for (const sourceObject of payload.objects.map(compactDocxObjectIdentity)) {
+        const candidate = [...objects, sourceObject];
+        if (objects.length > 0 && Buffer.byteLength(JSON.stringify(candidate)) > 6_500) break;
+        objects.push(sourceObject);
+      }
+      const nextOffset = offset + objects.length < totalCount ? offset + objects.length : null;
+      return {
+        ...retained,
+        schema: payload.schema,
+        receipt: {
+          schema: 'tiwater.docx-observation-receipt/v1',
+          operation: 'list',
+          totalCount,
+          returnedCount: objects.length,
+          remaining: totalCount - offset - objects.length,
+          nextOffset,
+        },
+        objects,
+      };
     }
     if (tool === 'docx_table_index') {
       const totalCount = payload.tables.length;
@@ -663,7 +700,50 @@ async function docxObservation(tool, args) {
         tables,
       };
     }
-    if (tool === 'docx_read_table') return { ...retained, ...payload };
+    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}`);
   });
 }
@@ -674,12 +754,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.10",
+  "version": "0.18.12",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",