@tiwater/office-mcp 0.16.20 → 0.17.1

package/office/README.md

@@ -17,8 +17,9 @@ OpenXML-internal identifiers, not filesystem arguments.
 
 ## Capability families
 
-- DOCX: inspect document/tables, export, compare, validate OpenXML, font, and table-of-contents styles
-  policy, transform styles, and batch one fixed edit action.
+- DOCX: inspect document/tables, export, compare, validate OpenXML, apply or validate font and
+  table-of-contents style policies, refresh document fields, replace object text, transform styles,
+  and batch one fixed edit action.
 - XLS/XLSX: convert legacy XLS with ET, inspect/export, validate, and batch
   one fixed workbook edit action.
 - PPTX: inspect/export, bind selected masters/layouts, apply text formatting,

package/office/contracts/docx_apply_font_policy.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/docx_apply_font_policy",
+  "type": "object",
+  "properties": {
+    "targetDocument": {
+      "type": "object",
+      "properties": {
+        "input": { "type": "string", "minLength": 1, "x-tiwater-file-role": "read" },
+        "revision": { "type": "string", "pattern": "^docx-rev-v1-[0-9a-f]{64}$" }
+      },
+      "required": ["input", "revision"],
+      "additionalProperties": false
+    },
+    "policy": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "read",
+      "description": "Path to the current caller-authorized tiwater.docx-font-policy/v1 JSON asset."
+    },
+    "output": { "type": "string", "minLength": 1, "x-tiwater-file-role": "write" },
+    "receiptOutput": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["targetDocument", "policy", "output", "receiptOutput"],
+  "additionalProperties": false
+}

package/office/contracts/docx_apply_toc_style_policy.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/docx_apply_toc_style_policy",
+  "type": "object",
+  "properties": {
+    "targetDocument": {
+      "type": "object",
+      "properties": {
+        "input": { "type": "string", "minLength": 1, "x-tiwater-file-role": "read" },
+        "revision": { "type": "string", "pattern": "^docx-rev-v1-[0-9a-f]{64}$" }
+      },
+      "required": ["input", "revision"],
+      "additionalProperties": false
+    },
+    "italic": { "type": "boolean" },
+    "indentCharactersPerLevel": { "type": "integer", "minimum": 0, "maximum": 21474836 },
+    "output": { "type": "string", "minLength": 1, "x-tiwater-file-role": "write" },
+    "receiptOutput": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["targetDocument", "italic", "indentCharactersPerLevel", "output", "receiptOutput"],
+  "additionalProperties": false
+}

package/office/contracts/docx_copy_content.schema.json

@@ -21,7 +21,7 @@
           "targetRef": {
             "type": "string",
             "pattern": "^dox1_[0-9a-f]{64}$",
-            "description": "Target cell ref whose content is replaced while its cell formatting is retained."
+            "description": "Target plain-text paragraph or cell ref whose content is replaced while its container formatting is retained. Paragraph bookmarks are preserved; targets containing fields, drawings, nested tables, controls, links, or other non-text content are rejected."
           },
           "sourceDocument": {
             "type": "object",
@@ -35,7 +35,7 @@
           "sourceSelections": {
             "type": "array",
             "minItems": 1,
-            "description": "Ordered source content copied into the target cell. Select a whole observed object by ref alone, or select an exact substring by adding range to an observed run or text ref. Multiple selections are copied in this array order.",
+            "description": "Ordered source content copied into the target paragraph or cell. Select a whole observed object by ref alone, or select an exact substring by adding range to an observed run or text ref. Multiple selections are copied in this array order.",
             "items": {
               "type": "object",
               "properties": {

package/office/contracts/docx_refresh_fields.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current DOCX document.",
+      "x-tiwater-file-role": "read"
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "New DOCX output path. Existing files are never overwritten.",
+      "x-tiwater-file-role": "write"
+    },
+    "receiptOutput": {
+      "type": "string",
+      "minLength": 1,
+      "description": "New JSON receipt path. Existing files are never overwritten.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["input", "output", "receiptOutput"],
+  "additionalProperties": false
+}

package/office/contracts/docx_set_text.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/docx_set_text",
+  "type": "object",
+  "properties": {
+    "targetDocument": {
+      "type": "object",
+      "properties": {
+        "input": { "type": "string", "minLength": 1, "x-tiwater-file-role": "read" },
+        "revision": { "type": "string", "pattern": "^docx-rev-v1-[0-9a-f]{64}$" }
+      },
+      "required": ["input", "revision"],
+      "additionalProperties": false
+    },
+    "changes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "targetRef": {
+            "type": "string",
+            "pattern": "^dox1_[0-9a-f]{64}$",
+            "description": "Observed plain-text paragraph or cell ref whose whole text content is replaced. Paragraph bookmarks are preserved; targets containing fields, drawings, nested tables, controls, links, or other non-text content are rejected."
+          },
+          "text": { "type": "string" }
+        },
+        "required": ["targetRef", "text"],
+        "additionalProperties": false
+      }
+    },
+    "output": { "type": "string", "minLength": 1, "x-tiwater-file-role": "write" },
+    "receiptOutput": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["targetDocument", "changes", "output", "receiptOutput"],
+  "additionalProperties": false
+}

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

@@ -2,9 +2,31 @@
   "schema": "tiwater.office-provider-contract-manifest/v1",
   "provider": {
     "id": "@tiwater/office-mcp",
-    "version": "0.16.20"
+    "version": "0.17.1"
   },
   "tools": [
+    {
+      "name": "docx_apply_font_policy",
+      "providerContract": {
+        "source": "packages/docx-cli/contracts/mcp-input/docx_apply_font_policy.schema.json",
+        "sha256": "153e50e2f6577b5ea70fd1d3522f8ccf3a74b82b683f1f8fe724f6433a9c72e0"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_apply_font_policy.schema.json",
+        "sha256": "153e50e2f6577b5ea70fd1d3522f8ccf3a74b82b683f1f8fe724f6433a9c72e0"
+      }
+    },
+    {
+      "name": "docx_apply_toc_style_policy",
+      "providerContract": {
+        "source": "packages/docx-cli/contracts/mcp-input/docx_apply_toc_style_policy.schema.json",
+        "sha256": "2d4887ab4dc57e2c655f130e67c08886ff1630a889e7258b13519fb6e1529d25"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_apply_toc_style_policy.schema.json",
+        "sha256": "2d4887ab4dc57e2c655f130e67c08886ff1630a889e7258b13519fb6e1529d25"
+      }
+    },
     {
       "name": "docx_compare",
       "providerContract": {
@@ -20,11 +42,11 @@
       "name": "docx_copy_content",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_copy_content.schema.json",
-        "sha256": "27110c4590087bb38bd08f77ab2dc19a62407a836f58a603d222ebdb184c97b6"
+        "sha256": "a988f7c4284c5f99bd3cc28f31813c0a12b999c2486f697776bf6f873c9c49e7"
       },
       "inputContract": {
         "path": "office/contracts/docx_copy_content.schema.json",
-        "sha256": "27110c4590087bb38bd08f77ab2dc19a62407a836f58a603d222ebdb184c97b6"
+        "sha256": "a988f7c4284c5f99bd3cc28f31813c0a12b999c2486f697776bf6f873c9c49e7"
       }
     },
     {
@@ -126,6 +148,17 @@
         "sha256": "29ba026050f1120219491f918e74c344551224795b1d15e49ec886d4e81e092a"
       }
     },
+    {
+      "name": "docx_refresh_fields",
+      "providerContract": {
+        "source": "packages/convert-cli/schemas/mcp-input/docx_refresh_fields.schema.json",
+        "sha256": "5f2a4f928796752adf7a44098919bca94c6faba8dbc9e5ad36b43e7f33035c7c"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_refresh_fields.schema.json",
+        "sha256": "5f2a4f928796752adf7a44098919bca94c6faba8dbc9e5ad36b43e7f33035c7c"
+      }
+    },
     {
       "name": "docx_replace_style_ids",
       "providerContract": {
@@ -137,6 +170,17 @@
         "sha256": "aa8fc12a350a391fadf32546847f29a816319efcab01866a1f406dc8313ea1ed"
       }
     },
+    {
+      "name": "docx_set_text",
+      "providerContract": {
+        "source": "packages/docx-cli/contracts/mcp-input/docx_set_text.schema.json",
+        "sha256": "945a5af0d9390c21f380cc9d255429353d6f743264b19a9e85111e75b3c0344b"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_set_text.schema.json",
+        "sha256": "945a5af0d9390c21f380cc9d255429353d6f743264b19a9e85111e75b3c0344b"
+      }
+    },
     {
       "name": "docx_split_cells",
       "providerContract": {

package/office/index.mjs

@@ -100,6 +100,31 @@ const nativeRenderOutput = z.object({
   }).strict(),
 }).strict();
 
+const docxFieldRefreshReceipt = z.object({
+  schema: z.literal('tiwater.convert-refresh-docx-fields/v1'),
+  status: z.literal('ok'),
+  input: z.string(),
+  input_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  output: z.string(),
+  output_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  source_format: z.literal('docx'),
+  target_format: z.literal('docx'),
+  version: z.string(),
+  backend: z.literal('wps'),
+  refresh_scope: z.array(z.enum(['table-of-contents', 'table-of-figures'])).min(1),
+}).strict();
+
+const docxFieldRefreshOutput = z.object({
+  tool: z.literal('docx_refresh_fields'),
+  runtime: runtimeIdentity,
+  output: artifact,
+  receipt: artifact,
+  summary: z.object({
+    backend: z.literal('wps'),
+    refreshScope: z.array(z.enum(['table-of-contents', 'table-of-figures'])).min(1),
+  }).strict(),
+}).strict();
+
 const xlsxFixedTools = [
   {"name":"xlsx_set_cell_value","description":"Set current workbook cell values."},
   {"name":"xlsx_set_cell_number_format","description":"Set current workbook cell number formats."},
@@ -173,6 +198,7 @@ const docxObjectIdentity = z.object({
 const docxReadObjectOutput = artifactOutput('docx_read_object').extend({
   revision: docxRevision,
   object: docxObjectIdentity,
+  objects: z.array(docxObjectIdentity).min(1),
 }).strict();
 
 const tools = [
@@ -200,7 +226,7 @@ const tools = [
   },
   {
     name: 'docx_read_object',
-    description: 'Read one selected native DOCX object as an ordered native hierarchy written to the requested output artifact. The tool response only identifies that artifact and the selected root object; read the artifact for descendant refs and content. For a table, request row and cell once. Add paragraph for whole-paragraph choices; add run and text for exact content selections.',
+    description: 'Read one selected native DOCX object. The response returns the selected root and requested descendants as ordered object identities for the next operation; the complete hierarchy remains in the evidence artifact. For a table, request row, cell, and paragraph once when row bounds, header columns, and paragraph choices are all needed.',
     inputSchema: inputContract('docx_read_object'),
     outputSchema: docxReadObjectOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -208,11 +234,18 @@ const tools = [
   },
   {
     name: 'docx_copy_content',
-    description: 'Replace content in existing target cells while retaining target cell formatting and source inline meaning. Batch cells that need exact observed subsets after docx_copy_table_rows. A selection copies a whole object by ref, or an exact substring when range is attached to a run or text ref.',
+    description: 'Replace content in existing plain-text target paragraphs or cells while retaining target container formatting and source inline meaning. Targets containing non-text objects are rejected. Batch cells that need exact observed subsets after docx_copy_table_rows. A selection copies a whole object by ref, or an exact substring when range is attached to a run or text ref.',
     inputSchema: inputContract('docx_copy_content'),
     outputSchema: fixedEditOutput('docx_copy_content'),
     handler: args => fixedEdit('docx_copy_content', args),
   },
+  {
+    name: 'docx_set_text',
+    description: 'Replace the whole text content of observed plain-text paragraph or cell objects while retaining their target formatting. Targets containing non-text objects are rejected. This sets already-derived text; it does not insert objects, 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_copy_table_rows',
     description: 'Populate existing target tables by replacing selected data-row ranges with selected source rows. Explicit header-cell mappings preserve target presentation and source grouping. A column content mode applies to every copied cell in that column; when cells need different subsets, copy the row structure first and batch those cells with docx_copy_content.',
@@ -277,6 +310,13 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true },
     handler: docxValidateFontPolicy,
   },
+  {
+    name: 'docx_apply_font_policy',
+    description: 'Apply one explicit font family and size policy to current main-document body and table text. It does not derive a policy or alter other run semantics.',
+    inputSchema: inputContract('docx_apply_font_policy'),
+    outputSchema: fixedEditOutput('docx_apply_font_policy'),
+    handler: args => fixedEdit('docx_apply_font_policy', args),
+  },
   {
     name: 'docx_validate_toc_style_policy',
     description: 'Validate current DOCX table-of-contents paragraph styles against an explicit policy.',
@@ -284,6 +324,20 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true },
     handler: docxValidateTocStylePolicy,
   },
+  {
+    name: 'docx_apply_toc_style_policy',
+    description: 'Apply explicit italic and per-level indentation values to current built-in table-of-contents paragraph styles. It does not change heading text or refresh fields.',
+    inputSchema: inputContract('docx_apply_toc_style_policy'),
+    outputSchema: fixedEditOutput('docx_apply_toc_style_policy'),
+    handler: args => fixedEdit('docx_apply_toc_style_policy', args),
+  },
+  {
+    name: 'docx_refresh_fields',
+    description: 'Refresh table-of-contents and table-of-figures field results in a current DOCX through native WPS Writer. It does not change headings, captions, or field definitions.',
+    inputSchema: inputContract('docx_refresh_fields'),
+    outputSchema: docxFieldRefreshOutput,
+    handler: docxRefreshFields,
+  },
   {
     name: 'docx_strip_direct_formatting',
     description: 'Remove direct paragraph and run formatting while preserving styles.',
@@ -429,6 +483,17 @@ function compactDocxObjectIdentity(object) {
   };
 }
 
+function compactDocxObservationObjects(observation) {
+  const objects = [];
+  function visit(node) {
+    if (!node?.object) return;
+    objects.push(compactDocxObjectIdentity(node.object));
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(observation);
+  return objects;
+}
+
 async function docxInspect(args) {
   const input = path.resolve(requireString(args.input, 'input'));
   const result = await runJsonCandidateChain(docxCandidates, ['inspect', input, '--json']);
@@ -461,6 +526,7 @@ async function docxReadObject(args) {
       artifact: await writeJsonArtifact(output, result.json),
       revision: result.json.receipt.revision,
       object: compactDocxObjectIdentity(result.json.observation.object),
+      objects: compactDocxObservationObjects(result.json.observation),
     };
   });
 }
@@ -492,6 +558,42 @@ async function docxReplaceStyleIds(args) {
   return withTempJsonFile(args.styleMap, styleMapPath => copyTransform('docx_replace_style_ids', docxCandidates, ['replace-style-ids'], args, [styleMapPath]));
 }
 
+async function docxRefreshFields(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  const output = path.resolve(requireString(args.output, 'output'));
+  const receiptOutput = path.resolve(requireString(args.receiptOutput, 'receiptOutput'));
+  if (path.extname(input).toLowerCase() !== '.docx' || path.extname(output).toLowerCase() !== '.docx') {
+    throw Object.assign(new Error('DOCX field refresh requires .docx input and output'), { code: -32602 });
+  }
+  await requireNewFile(output, 'output');
+  await requireNewFile(receiptOutput, 'receiptOutput');
+  const inputArtifact = await fileArtifact(input);
+  try {
+    const result = await runJsonCandidateChain(convertCandidates, ['refresh-docx-fields', input, output]);
+    const providerReceipt = docxFieldRefreshReceipt.parse(result.json);
+    const outputArtifact = await fileArtifact(output);
+    if (path.resolve(providerReceipt.input) !== input
+        || path.resolve(providerReceipt.output) !== output
+        || providerReceipt.input_sha256 !== inputArtifact.sha256
+        || providerReceipt.output_sha256 !== outputArtifact.sha256) {
+      throw new Error('DOCX field refresh receipt is not bound to the current input and output');
+    }
+    return {
+      tool: 'docx_refresh_fields',
+      runtime: commandRuntime(result),
+      output: outputArtifact,
+      receipt: await writeJsonArtifact(receiptOutput, providerReceipt),
+      summary: {
+        backend: providerReceipt.backend,
+        refreshScope: providerReceipt.refresh_scope,
+      },
+    };
+  } catch (error) {
+    await rm(output, { force: true });
+    throw error;
+  }
+}
+
 async function copyTransform(tool, candidates, command, args, suffix = []) {
   const input = path.resolve(requireString(args.input, 'input'));
   const output = path.resolve(requireString(args.output, 'output'));

package/package.json

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