@tiwater/office-mcp 0.21.22 → 0.21.28

package/office/contracts/docx_fill_table_from_tables.schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "tiwater.office-mcp-input/docx_fill_table_from_tables",
+  "description": "Project source-table rows into one target template table atomically. Use this instead of manually rebuilding rows when target cells derive from source tables. Target formatting is reused, and native vertical-merge owners are preserved within each source range.",
   "type": "object",
   "properties": {
     "input": { "type": "string", "minLength": 1, "description": "Current target DOCX.", "x-tiwater-file-role": "read" },
@@ -96,7 +97,7 @@
           },
           "recordColumn": {
             "type": "object",
-            "description": "Source grid-column address whose native vertical-merge owners define consecutive logical records. An unmerged cell defines one record.",
+            "description": "Source grid-column address that defines output-row records. Choose an unmerged column when every physical source row must remain an output row; vertical merges in other mapped columns are still preserved. Choose a merged column only when every mapping into one target cell has one equal scalar value throughout that merge group.",
             "properties": {
               "part": { "type": "string", "minLength": 1, "pattern": "^\\/" },
               "path": { "type": "string", "pattern": "^\\/[A-Za-z_][A-Za-z0-9_.-]*:[A-Za-z_][A-Za-z0-9_.-]*\\[[1-9][0-9]*\\](?:\\/[A-Za-z_][A-Za-z0-9_.-]*:[A-Za-z_][A-Za-z0-9_.-]*\\[[1-9][0-9]*\\])*$" }

package/office/contracts/docx_replace_content_from_source.schema.json

@@ -44,13 +44,13 @@
           "sourceSelections": {
             "minItems": 1,
             "type": "array",
-            "description": "Ordered native source paragraphs, runs, or text nodes. Their selected inline content becomes the target content without Agent transcription.",
+            "description": "Ordered native source cells, paragraphs, runs, or text nodes. Consecutive run or text selections from one source paragraph form one target paragraph; a range retains the native runs it crosses. A source paragraph boundary remains a target paragraph boundary. Selected content becomes the target content without Agent transcription.",
             "items": {
               "type": "object",
               "properties": {
                 "address": {
                   "type": "object",
-                  "description": "Native source object address returned by docx_read_object or docx_read_table. Selecting a paragraph copies that paragraph's inline content; selecting a cell copies its direct paragraphs.",
+                  "description": "Native source object address returned by docx_read_object or docx_read_table. Selecting a paragraph copies that paragraph's inline content; selecting a cell copies its direct paragraphs; selecting a run or text copies native inline content and formatting.",
                   "properties": {
                     "part": {
                       "type": "string",
@@ -70,7 +70,7 @@
                 },
                 "range": {
                   "type": "object",
-                  "description": "Optional Unicode-scalar substring of a selected run or text node. Omit it to copy the complete selected object.",
+                  "description": "Optional Unicode-scalar substring of the selected object's observed text. For a cell, offsets use its docx_read_table text with one newline between direct paragraphs. The selected native runs and paragraph boundaries are retained. Omit it to copy the complete selected object.",
                   "properties": {
                     "start": {
                       "type": "integer",

package/office/contracts/docx_set_paragraph_pagination.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/docx_set_paragraph_pagination",
+  "type": "object",
+  "properties": {
+    "input": { "type": "string", "minLength": 1, "x-tiwater-file-role": "read" },
+    "changes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "paragraph": {
+            "type": "object",
+            "properties": {
+              "part": { "type": "string", "minLength": 1, "pattern": "^\\/" },
+              "path": { "type": "string", "pattern": "^\\/[A-Za-z_][A-Za-z0-9_.-]*:[A-Za-z_][A-Za-z0-9_.-]*\\[[1-9][0-9]*\\](?:\\/[A-Za-z_][A-Za-z0-9_.-]*:[A-Za-z_][A-Za-z0-9_.-]*\\[[1-9][0-9]*\\])*$" }
+            },
+            "required": ["part", "path"],
+            "additionalProperties": false
+          },
+          "keepWithNext": { "type": "boolean", "description": "Keep this paragraph on the same page as the immediately following paragraph or table. This does not guarantee that a table header remains with its first body row." },
+          "keepLinesTogether": { "type": "boolean", "description": "Keep all lines of this paragraph on one page." },
+          "pageBreakBefore": { "type": "boolean", "description": "Start this paragraph on a new page." },
+          "preventWidowOrphanLines": { "type": "boolean", "description": "Prevent a single first or last line from being isolated across pages." }
+        },
+        "required": ["paragraph"],
+        "additionalProperties": false
+      }
+    },
+    "output": { "type": "string", "minLength": 1, "description": "Output DOCX path; may equal input for one atomic in-place update.", "x-tiwater-file-role": "write" },
+    "receiptOutput": { "type": "string", "minLength": 1, "x-tiwater-file-role": "write", "x-tiwater-file-effect": false }
+  },
+  "required": ["input", "changes", "output", "receiptOutput"],
+  "additionalProperties": false
+}

package/office/contracts/docx_set_table_body.schema.json

@@ -94,7 +94,10 @@
                   "description": "One or more contiguous request-local column IDs occupied by this cell.",
                   "items": { "type": "string", "minLength": 1, "maxLength": 80 }
                 },
-                "text": { "type": "string" },
+                "text": {
+                  "type": "string",
+                  "description": "Final plain text for this cell. If the current cell at the same row and grid span already has exactly this text, its native paragraphs and run formatting are retained while row and merge properties are updated."
+                },
                 "rowSpan": {
                   "type": "integer",
                   "minimum": 1,
@@ -105,6 +108,10 @@
               "required": ["columns", "text"],
               "additionalProperties": false
             }
+          },
+          "cantSplit": {
+            "type": "boolean",
+            "description": "Whether Word may split this physical row across pages. Omit to preserve the prototype row property."
           }
         },
         "required": ["prototypeRow", "cells"],

package/office/contracts/docx_table_index.schema.json

@@ -19,12 +19,6 @@
       "description": "Optional new JSON artifact path for retaining the complete table index. May be combined with returnContent.",
       "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,

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.22"
+    "version": "0.21.28"
   },
   "tools": [
     {
@@ -75,11 +75,11 @@
       "name": "docx_fill_table_from_tables",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_fill_table_from_tables.schema.json",
-        "sha256": "f4778f68707c1bc505bd1b38c26508b9ff80d2bc1a361f1630ecb70dbc6a542e"
+        "sha256": "4e80fff1c08fd16f8a5b4c638cf6469aa51e3a499743b44f3bf900ae7194ea9b"
       },
       "inputContract": {
         "path": "office/contracts/docx_fill_table_from_tables.schema.json",
-        "sha256": "f4778f68707c1bc505bd1b38c26508b9ff80d2bc1a361f1630ecb70dbc6a542e"
+        "sha256": "4e80fff1c08fd16f8a5b4c638cf6469aa51e3a499743b44f3bf900ae7194ea9b"
       }
     },
     {
@@ -174,11 +174,11 @@
       "name": "docx_replace_content_from_source",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_replace_content_from_source.schema.json",
-        "sha256": "d6ce53f684ea0991508cab930e101c910ac05e9725cc25d5312806070c20d320"
+        "sha256": "3ce7730317f1b9429f5da38b0eaecb53664a056545904a7f3904cdf148b94ad1"
       },
       "inputContract": {
         "path": "office/contracts/docx_replace_content_from_source.schema.json",
-        "sha256": "d6ce53f684ea0991508cab930e101c910ac05e9725cc25d5312806070c20d320"
+        "sha256": "3ce7730317f1b9429f5da38b0eaecb53664a056545904a7f3904cdf148b94ad1"
       }
     },
     {
@@ -192,15 +192,26 @@
         "sha256": "25f4d4e7c69fa5a2c4a82621aa58ea8eda21245636f84f2243ca4e9092616b68"
       }
     },
+    {
+      "name": "docx_set_paragraph_pagination",
+      "providerContract": {
+        "source": "packages/docx-cli/contracts/mcp-input/docx_set_paragraph_pagination.schema.json",
+        "sha256": "ccb90bb5b811cfc82985050094637b1afe4c9daf51d7243c0d81b2d63d875825"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_set_paragraph_pagination.schema.json",
+        "sha256": "ccb90bb5b811cfc82985050094637b1afe4c9daf51d7243c0d81b2d63d875825"
+      }
+    },
     {
       "name": "docx_set_table_body",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_set_table_body.schema.json",
-        "sha256": "c1d462210f14b6a2761d4056e0a3001925987e53e38075a5c44572d0b37d289b"
+        "sha256": "adb0898a253a60fc80e3e811fdd6d19ac01ae76abe16b077e8af1f0960b640af"
       },
       "inputContract": {
         "path": "office/contracts/docx_set_table_body.schema.json",
-        "sha256": "c1d462210f14b6a2761d4056e0a3001925987e53e38075a5c44572d0b37d289b"
+        "sha256": "adb0898a253a60fc80e3e811fdd6d19ac01ae76abe16b077e8af1f0960b640af"
       }
     },
     {
@@ -240,11 +251,11 @@
       "name": "docx_table_index",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_table_index.schema.json",
-        "sha256": "a5f43ef56c14dfa846d4823b244cadac141f45fe1b716782df421c270f6efc5e"
+        "sha256": "737052f653fe0d222bfc2b808e0fbc298376ab88cf052352888ff02e5b71ed52"
       },
       "inputContract": {
         "path": "office/contracts/docx_table_index.schema.json",
-        "sha256": "a5f43ef56c14dfa846d4823b244cadac141f45fe1b716782df421c270f6efc5e"
+        "sha256": "737052f653fe0d222bfc2b808e0fbc298376ab88cf052352888ff02e5b71ed52"
       }
     },
     {
@@ -445,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/docx-object-identity.mjs

@@ -0,0 +1,11 @@
+export function compactDocxObjectIdentity(object) {
+  return {
+    address: object.address,
+    parentAddress: object.parentAddress ?? null,
+    kind: object.kind,
+    textPreview: object.textPreview ?? null,
+    gridSpan: object.gridSpan ?? null,
+    verticalMerge: object.verticalMerge ?? null,
+    verticalTextAlignment: object.verticalTextAlignment ?? null,
+  };
+}

package/office/index.mjs

@@ -23,6 +23,7 @@ import {
   writeJsonArtifact,
 } from '../_shared/large-json-result.mjs';
 import { withOutputWriteLock } from '../_shared/output-write-lock.mjs';
+import { compactDocxObjectIdentity } from './docx-object-identity.mjs';
 
 const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
 const inputContractManifest = JSON.parse(await readFile(
@@ -201,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(),
@@ -237,7 +299,7 @@ function docxInspectionOutput(tool) {
         address: docxAddress,
         textPreview: z.string().min(1).max(240),
       }).strict()).max(6),
-    }).strict().optional(),
+    }).strict(),
   }).strict();
 }
 
@@ -248,6 +310,7 @@ const docxObjectIdentity = z.object({
   textPreview: z.string().nullable(),
   gridSpan: z.number().int().positive().nullable(),
   verticalMerge: z.string().nullable(),
+  verticalTextAlignment: z.enum(['baseline', 'superscript', 'subscript']).nullable(),
 }).strict();
 
 const docxNestedObjectIdentity = docxObjectIdentity.pick({
@@ -259,6 +322,7 @@ const docxNestedObjectIdentity = docxObjectIdentity.pick({
   verticalMerge: z.string().optional(),
   verticalMergeOwner: docxAddress.optional(),
   logicalText: z.string().optional(),
+  verticalTextAlignment: z.enum(['baseline', 'superscript', 'subscript']).optional(),
 }).strict();
 const docxObservationNode = z.lazy(() => z.object({
   object: docxNestedObjectIdentity,
@@ -292,21 +356,11 @@ const docxTableIndexOutput = docxObservationOutput('docx_table_index').extend({
   }).strict(),
   tables: z.array(z.object({
     address: docxAddress,
-    parentAddress: docxAddress.nullable(),
     rowCount: z.number().int().nonnegative(),
     columnCount: z.number().int().nonnegative(),
     textPreview: z.string(),
-    textLength: z.number().int().nonnegative(),
-    precedingParagraph: z.object({
-      address: docxAddress,
-      textPreview: z.string(),
-      textLength: z.number().int().nonnegative(),
-    }).strict().nullable(),
-    followingParagraph: z.object({
-      address: docxAddress,
-      textPreview: z.string(),
-      textLength: z.number().int().nonnegative(),
-    }).strict().nullable(),
+    precedingText: z.string().nullable(),
+    followingText: z.string().nullable(),
   }).strict()).optional(),
 }).strict();
 
@@ -370,7 +424,7 @@ const docxReadObjectOutput = docxObservationOutput('docx_read_object').extend({
 const tools = [
   {
     name: 'docx_inspect',
-    description: 'Inspect one current DOCX. Set returnContent true to return the compact identity summary. Provide output to retain the complete machine observation and return its artifact receipt. These channels are independent and may be used together. At least one channel is required. Use list and read operations to traverse selected document objects in native structure order.',
+    description: 'Inspect one current DOCX for identity and package overview. The response always includes a bounded identity summary. Set returnContent true when that summary is the requested direct result. Provide output to retain the complete machine observation and return its artifact receipt. These channels are independent and may be used together. At least one channel is required. Use list and read operations to traverse selected document objects in native structure order. This overview is not a complete final-document readback; use docx_export_json when a downstream consumer requires the complete body projection.',
     inputSchema: inputContract('docx_inspect'),
     outputSchema: docxInspectionOutput('docx_inspect'),
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -386,7 +440,7 @@ const tools = [
   },
   {
     name: 'docx_table_index',
-    description: 'Locate tables in one current DOCX without returning full cell content or deciding table semantics. Set returnContent true to return a bounded page of addresses, shapes, short previews, and nearest non-empty paragraphs. Provide output to store the complete index and return its artifact receipt. These channels are independent and may be used together; at least one is required. Continue from receipt.nextOffset only when an unreturned table is needed for the current decision, then read one selected native address.',
+    description: 'Locate tables in one current DOCX without returning full cell content or deciding table semantics. Set returnContent true to return as many compact native addresses, shapes, and short text clues as fit the bounded response; the provider chooses page size. Provide output to store the complete index and return its artifact receipt. These channels are independent and may be used together; at least one is required. Continue from receipt.nextOffset only when an unreturned table is needed for the current decision, then pass one returned address unchanged to a narrow table or object read.',
     inputSchema: inputContract('docx_table_index'),
     outputSchema: docxTableIndexOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -394,7 +448,7 @@ const tools = [
   },
   {
     name: 'docx_read_object',
-    description: 'Read explicitly selected rows, cells, or paragraphs from one native DOCX. Set returnContent true to return compact requested descendants; if receipt.narrowingRequired is true, request fewer addresses or descendant kinds. Provide output to store the complete selected observation and return its artifact receipt. These channels are independent and may be used together; at least one is required. A selected cell exposes its vertical-merge owner and logical text, so a continue cell keeps its physical identity while resolving the restart cell value. Use docx_read_table for a table range.',
+    description: 'Read explicitly selected rows, cells, or paragraphs from one native DOCX. Set returnContent true to return compact requested descendants; if receipt.narrowingRequired is true, request fewer addresses or descendant kinds. Provide output to store the complete selected observation and return its artifact receipt. These channels are independent and may be used together; at least one is required. A selected cell exposes its vertical-merge owner and logical text, so a continue cell keeps its physical identity while resolving the restart cell value. Run and text descendants expose their native verticalTextAlignment when it is baseline, superscript, or subscript. Use docx_read_table for a table range.',
     inputSchema: inputContract('docx_read_object'),
     outputSchema: docxReadObjectOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -402,7 +456,7 @@ const tools = [
   },
   {
     name: 'docx_read_table',
-    description: 'Read an explicit row range from exactly one table selected by native OpenXML address; it never builds another whole-table data object. Set returnContent true to return a byte-bounded compact row page. Provide output to store full paragraph and text-node detail for the selected row page and return its artifact receipt. These channels are independent and may be used together; at least one is required. Request only rows needed for the current decision; receipt.remaining is navigation information, not an obligation to read unused rows, and blank template rows need not be paged through. receipt.nextOffset is present only when another row page exists. Each returned row and cell keeps its reusable native address, zero-based logical gridColumnStart, gridSpan, vertical-merge owner, physical text, and logical text. Match columns across rows by gridColumnStart; a tc[n] path or array position is only that row\'s physical cell ordinal and is not a column identity when gridSpan or gridBefore is present. In a vertical merge, restart begins one logical cell and a continue cell is not an independent row value: logicalText resolves the restart cell value while text remains the physical cell value. Use docx_read_object when one exact object needs a narrower descendant view. The provider reports physical structure only; the Agent decides template and business meaning.',
+    description: 'Read an explicit row range from exactly one table selected by native OpenXML address; it never builds another whole-table data object. Set returnContent true to return a byte-bounded compact row page. Provide output to store full paragraph and text-node detail, including native verticalTextAlignment, for the selected row page and return its artifact receipt. These channels are independent and may be used together; at least one is required. Request only rows needed for the current decision; receipt.remaining is navigation information, not an obligation to read unused rows, and blank template rows need not be paged through. receipt.nextOffset is present only when another row page exists. Each returned row and cell keeps its reusable native address, zero-based logical gridColumnStart, gridSpan, vertical-merge owner, physical text, and logical text. Match columns across rows by gridColumnStart; a tc[n] path or array position is only that row\'s physical cell ordinal and is not a column identity when gridSpan or gridBefore is present. In a vertical merge, restart begins one logical cell and a continue cell is not an independent row value: logicalText resolves the restart cell value while text remains the physical cell value. Use docx_read_object when one exact object needs a narrower descendant view. The provider reports physical structure only; the Agent decides template and business meaning.',
     inputSchema: inputContract('docx_read_table'),
     outputSchema: docxTableReadOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -410,28 +464,35 @@ const tools = [
   },
   {
     name: 'docx_replace_content_from_source',
-    description: 'Replace existing target paragraph or table-cell content from explicitly selected native source paragraphs, runs, text nodes, or exact text ranges while retaining target container formatting and table structure. Use it after docx_fill_table_from_tables when the target needs selected source child content instead of the whole source cell; supply returned target-cell addresses and observed source descendant addresses, never retype source-owned text. It does not copy source rows, cells, spans, or merges.',
+    description: 'Replace existing target paragraph or table-cell content from explicitly selected native source cells, paragraphs, runs, text nodes, or exact text ranges while retaining target container formatting and table structure. For a source cell already returned by docx_read_table, select a Unicode-scalar range directly against its returned text; the provider retains every crossed native run, including superscript and subscript, without another descendant read. Consecutive run or text selections from one source paragraph form one target paragraph, and source paragraph boundaries remain paragraph boundaries. Use it after docx_fill_table_from_tables when the target needs selected source content instead of the whole source cell; pass returned addresses unchanged and never retype source-owned text. It does not copy source rows, cells, spans, or merges.',
     inputSchema: inputContract('docx_replace_content_from_source'),
     outputSchema: fixedEditOutput('docx_replace_content_from_source'),
     handler: args => fixedEdit('docx_replace_content_from_source', args),
   },
   {
     name: 'docx_set_text',
-    description: 'Replace the whole text content of paragraph or cell objects observed from this exact input DOCX while retaining target formatting, bookmarks, spans, and vertical merges. For a vertically merged logical cell, write its visible text to the restart cell rather than a continue cell. Tabs and line breaks remain native document text controls; targets containing non-text objects are rejected. This sets already-derived text; it does not insert objects, change table structure, copy source formatting, or decide business wording.',
+    description: 'Replace the whole text content of paragraph or cell objects observed from this exact input DOCX while retaining target formatting, bookmarks, spans, and vertical merges. For a vertically merged logical cell, write its visible text to the restart cell rather than a continue cell. Tabs and line breaks remain native document text controls; targets containing non-text objects are rejected. Use this only for newly derived text. Content copied or selected from a source DOCX uses docx_replace_content_from_source so native runs such as superscript and subscript are retained. This does not insert objects, change table structure, copy source formatting, or decide business wording.',
     inputSchema: inputContract('docx_set_text'),
     outputSchema: fixedEditOutput('docx_set_text'),
     handler: args => fixedEdit('docx_set_text', args),
   },
+  {
+    name: 'docx_set_paragraph_pagination',
+    description: 'Set native pagination properties on explicitly selected current DOCX paragraphs. Each change sets at least one pagination property. keepWithNext keeps a paragraph with the immediately following paragraph or table but does not guarantee that a table header remains with its first body row. keepLinesTogether keeps one paragraph on one page; pageBreakBefore starts it on a new page; preventWidowOrphanLines controls isolated first or last lines. Omitted properties remain unchanged. The caller chooses paragraphs from current native addresses; the provider does not decide document layout or business meaning.',
+    inputSchema: inputContract('docx_set_paragraph_pagination'),
+    outputSchema: fixedEditOutput('docx_set_paragraph_pagination'),
+    handler: args => fixedEdit('docx_set_paragraph_pagination', args),
+  },
   {
     name: 'docx_set_table_body',
-    description: 'Atomically replace one exact current target-table row range while retaining the table, target styles, grid widths, and all rows and surrounding content outside the range. When retaining leading rows reported with repeatHeader=true, existingRows starts after all of them and never at a verticalMerge=continue row. Name every target grid column in native order and choose one current row inside existingRows as the style prototype for each final row. Horizontal spans use contiguous column IDs. Set rowSpan on one logical cell to occupy multiple rows and omit those columns from the covered rows; the provider writes native vertical merge cells. Every other grid column remains explicit. Every explicit cell includes an already-derived value; source-owned content is not retyped here. An empty final row array removes the range when another table row remains. The provider commits once and returns structural readback. It does not read source tables, map source to target, derive text, choose business columns, identify headers, or accept non-text cell content; use docx_fill_table_from_tables and docx_replace_content_from_source for source-owned table content.',
+    description: 'Atomically replace one exact current target-table row range while retaining the table, target styles, grid widths, and all rows and surrounding content outside the range. When retaining leading rows reported with repeatHeader=true, existingRows starts after all of them and never at a verticalMerge=continue row. Name every target grid column in native order and choose one current row inside existingRows as the style prototype for each final row. Horizontal spans use contiguous column IDs. Set rowSpan on one logical cell to occupy multiple rows and omit those columns from the covered rows; the provider writes native vertical merge cells. Set cantSplit on a final physical row when it must remain whole across page boundaries; omit it to preserve the prototype row property. Every other grid column remains explicit. Every explicit cell includes an already-derived value; source-owned content is not retyped here. An empty final row array removes the range when another table row remains. The provider commits once and returns structural readback. It does not read source tables, map source to target, derive text, choose business columns, identify headers, or accept non-text cell content; use docx_fill_table_from_tables and docx_replace_content_from_source for source-owned table content.',
     inputSchema: inputContract('docx_set_table_body'),
     outputSchema: fixedEditOutput('docx_set_table_body'),
     handler: args => fixedEdit('docx_set_table_body', args),
   },
   {
     name: 'docx_fill_table_from_tables',
-    description: 'Fill one current target-table body from one or more explicitly ordered current source-table row ranges. For each source, select the grid column whose native vertical merges define logical records and map its grid columns onto every target prototype cell. The provider concatenates source records in declared order, preserves horizontal spans, rebuilds vertical merges only within each source range, validates the complete target grid, commits once, and returns structural readback. It does not discover source tables, choose source or target business meaning, filter records, translate or rewrite text, or apply business-specific rules. A single source uses the same sources array with one item. When only selected source paragraphs belong in the target, use its returned target-cell addresses with docx_replace_content_from_source before readback.',
+    description: 'Fill one current target-table body from one or more explicitly ordered current source-table row ranges. For each source, select an unmerged record column when every physical source row must remain an output row; mapped columns still retain their native vertical merges. Select a merged record column only when every mapping into one target cell has one equal scalar value throughout that merge group. Map source grid columns onto every target prototype cell. The provider concatenates source records in declared order, copies each mapped source cell in full, preserves horizontal spans, rebuilds vertical merges only within each source range, validates the complete target grid, commits once, and returns structural readback. It does not discover source tables, choose source or target business meaning, filter records, translate or rewrite text, or apply business-specific rules. A single source uses the same sources array with one item. If a target needs only selected source descendants, such as one language from a bilingual cell, immediately use the returned target-cell addresses with docx_replace_content_from_source before releasing that source or reading back the completed target.',
     inputSchema: inputContract('docx_fill_table_from_tables'),
     outputSchema: fixedEditOutput('docx_fill_table_from_tables'),
     handler: args => fixedEdit('docx_fill_table_from_tables', args),
@@ -488,7 +549,7 @@ const tools = [
   },
   {
     name: 'docx_export_json',
-    description: 'Produce a body-only DOCX JSON projection only when a downstream consumer explicitly requires that format. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required. This does not replace bounded list and read operations.',
+    description: 'Produce the complete body-only DOCX JSON projection required for final-document readback or another downstream consumer of that format. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required. This does not replace bounded list and read operations during document processing.',
     inputSchema: inputContract('docx_export_json'),
     outputSchema: largeResultOutput('docx_export_json'),
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -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',
@@ -692,32 +761,17 @@ function compactDocxInspection(report) {
   };
 }
 
-function compactDocxObjectIdentity(object) {
-  return {
-    address: object.address,
-    parentAddress: object.parentAddress,
-    kind: object.kind,
-    textPreview: object.textPreview,
-    gridSpan: object.gridSpan,
-    verticalMerge: object.verticalMerge,
-  };
-}
-
 function compactTableIndexEntry(table) {
-  const paragraph = value => value === null ? null : {
-    address: value.address,
-    textPreview: value.textPreview.trim().replace(/\s+/gu, ' ').slice(0, 160),
-    textLength: value.textLength,
-  };
+  const paragraphText = value => value === null
+    ? null
+    : value.textPreview.trim().replace(/\s+/gu, ' ').slice(0, 32);
   return {
     address: table.address,
-    parentAddress: table.parentAddress,
     rowCount: table.rowCount,
     columnCount: table.columnCount,
-    textPreview: table.textPreview.trim().replace(/\s+/gu, ' ').slice(0, 240),
-    textLength: table.textLength,
-    precedingParagraph: paragraph(table.precedingParagraph),
-    followingParagraph: paragraph(table.followingParagraph),
+    textPreview: table.textPreview.trim().replace(/\s+/gu, ' ').slice(0, 64),
+    precedingText: paragraphText(table.precedingParagraph),
+    followingText: paragraphText(table.followingParagraph),
   };
 }
 
@@ -734,6 +788,7 @@ function compactDocxObservation(observation) {
       ...(identity.verticalMerge === null ? {} : { verticalMerge: identity.verticalMerge }),
       ...(node.object.verticalMergeOwner === null ? {} : { verticalMergeOwner: node.object.verticalMergeOwner }),
       ...(node.object.logicalText === null ? {} : { logicalText: node.object.logicalText }),
+      ...(identity.verticalTextAlignment === null ? {} : { verticalTextAlignment: identity.verticalTextAlignment }),
     };
     return {
       object,
@@ -755,7 +810,7 @@ async function docxInspect(args) {
     artifact: delivery.output === null
       ? null
       : await writeIdempotentJsonArtifact(delivery.output, result.json),
-    ...(delivery.returnContent ? compactDocxInspection(result.json) : {}),
+    ...compactDocxInspection(result.json),
   };
 }
 
@@ -829,9 +884,8 @@ async function docxObservation(tool, args) {
         };
       }
       const offset = Math.min(args.offset ?? 0, totalCount);
-      const requestedLimit = args.limit ?? totalCount;
       const tables = [];
-      for (const sourceTable of payload.tables.slice(offset, offset + requestedLimit)) {
+      for (const sourceTable of payload.tables.slice(offset)) {
         const table = compactTableIndexEntry(sourceTable);
         const candidate = [...tables, table];
         if (tables.length > 0
@@ -1217,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.22",
+  "version": "0.21.28",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
     "_shared/large-json-result.mjs",
     "_shared/output-write-lock.mjs",
     "office/index.mjs",
+    "office/docx-object-identity.mjs",
     "office/README.md",
     "office/contracts/tiwater-office-provider-contract-manifest-v1.json",
     "office/contracts/*.schema.json"