@tiwater/office-mcp 0.10.0 → 0.11.0

package/office/README.md

@@ -14,6 +14,7 @@ Shared stdio MCP server for Office document workflows.
 - `office_render_pdf`
 - `xlsx_inspect`
 - `xlsx_export_json`
+- `xlsx_apply`
 - `xlsx_validate`
 - `pptx_inspect`
 - `pptx_export_json`
@@ -23,6 +24,15 @@ Shared stdio MCP server for Office document workflows.
 Install `@tiwater/office-mcp` together with the runtime versions required by
 the consumer, then run `tiwater-office-mcp` as a stdio MCP server.
 
+Office MCP 0.11 requires these minimum published runtimes on `PATH`:
+
+| Command | Package | Minimum version |
+| --- | --- | --- |
+| `tiwater-docx` | NuGet `tiwater.docx.cli` | 0.15.0 |
+| `tiwater-xlsx` | NuGet `tiwater.xlsx.cli` | 0.2.55 |
+| `tiwater-pptx` | NuGet `tiwater.pptx.cli` | 0.2.22 |
+| `tiwater-convert` | NuGet `tiwater.convert.cli` | 0.9.22 |
+
 The server invokes published `tiwater-docx`, `tiwater-xlsx`,
 `tiwater-pptx`, and `tiwater-convert` commands from `PATH`. It does not require
 a source checkout or fall back to local projects.
@@ -32,6 +42,16 @@ tool arguments and structured results before they cross the protocol boundary.
 Large observations and exports are written to a caller-selected new JSON
 artifact. MCP returns only the artifact path, hash, and byte count.
 
+## Workbook editing
+
+`xlsx_apply` executes one existing `tiwater.xlsx-edit/v1` artifact against a
+current `.xlsx` workbook. The caller's deterministic builder owns all values,
+coordinates, and operation selection. Office MCP binds the current input,
+operations artifact, and created output by path and content hash and records the
+complete runtime result in a new receipt artifact. It does not interpret
+scenario knowledge or derive workbook edits. Callers independently inspect and
+validate the resulting workbook before delivery.
+
 ## Template migration
 
 Template migration separates business choice from document mechanics:

package/office/index.mjs

@@ -138,6 +138,39 @@ const artifact = z.object({
   bytes: z.number().int().nonnegative(),
 }).strict();
 
+const xlsxAppliedOperation = z.object({
+  type: z.string().min(1),
+  applied: z.boolean(),
+  detail: z.string(),
+  sheet: z.string().nullable().optional(),
+  changedRange: z.string().nullable().optional(),
+  warnings: z.array(z.string()).nullable().optional(),
+}).strict();
+const xlsxEditResult = z.object({
+  input: z.string().min(1),
+  output: z.string().min(1),
+  appliedOperations: z.array(xlsxAppliedOperation),
+}).strict();
+const xlsxApplyReceipt = z.object({
+  schema: z.literal('tiwater.office.xlsx-apply-receipt/v1'),
+  pass: z.boolean(),
+  input: artifact,
+  operations: artifact,
+  output: artifact.nullable(),
+  appliedOperations: z.array(xlsxAppliedOperation),
+}).strict();
+const xlsxApplyOutput = z.object({
+  tool: z.literal('xlsx_apply'),
+  runtime: runtimeIdentity,
+  receipt: artifact,
+  output: artifact.nullable(),
+  summary: z.object({
+    pass: z.boolean(),
+    operationCount: z.number().int().nonnegative(),
+    appliedCount: z.number().int().nonnegative(),
+  }).strict(),
+}).strict();
+
 const renderFileIdentity = z.object({
   sha256: z.string().regex(/^[a-f0-9]{64}$/),
   size_bytes: z.number().int().positive(),
@@ -358,6 +391,18 @@ const tools = [
     outputSchema: artifactOutput('xlsx_export_json'),
     handler: xlsxExportJson,
   },
+  {
+    name: 'xlsx_apply',
+    description: 'Apply one deterministic XLSX operations artifact to a current workbook. This tool executes published workbook edits; it does not derive values, coordinates, or business decisions.',
+    inputSchema: z.object({
+      input: pathInput.describe('Path to the current XLSX workbook.'),
+      operations: pathInput.describe('Path to the deterministic tiwater.xlsx-edit/v1 operations artifact.'),
+      output: pathInput.describe('New XLSX output path. Existing files are never overwritten.'),
+      receiptOutput: pathInput.describe('New JSON receipt path. Existing files are never overwritten.'),
+    }).strict(),
+    outputSchema: xlsxApplyOutput,
+    handler: xlsxApply,
+  },
   {
     name: 'xlsx_validate',
     description: 'Validate an XLSX workbook package and return Open XML validation evidence.',
@@ -961,6 +1006,56 @@ async function xlsxExportJson(args) {
   };
 }
 
+async function xlsxApply(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  const operations = path.resolve(requireString(args.operations, 'operations'));
+  const output = path.resolve(requireString(args.output, 'output'));
+  const receiptOutput = path.resolve(requireString(args.receiptOutput, 'receiptOutput'));
+  if (path.extname(input).toLowerCase() !== '.xlsx' || path.extname(output).toLowerCase() !== '.xlsx') {
+    throw Object.assign(new Error('XLSX apply input and output must use the .xlsx extension'), { code: -32602 });
+  }
+  await requireNewFile(output, 'output');
+  await requireNewFile(receiptOutput, 'receiptOutput');
+  const inputArtifact = await fileArtifact(input);
+  const operationsArtifact = await fileArtifact(operations);
+  await mkdir(path.dirname(output), { recursive: true });
+  try {
+    const result = await runJsonCandidateChain(
+      xlsxCandidates,
+      ['edit', input, operations, output],
+      { allowedExitCodes: [0, 1] });
+    const edit = xlsxEditResult.parse(result.json);
+    if (path.resolve(edit.input) !== input || path.resolve(edit.output) !== output) {
+      throw new Error('XLSX edit receipt is not bound to the current input and output');
+    }
+    const pass = edit.appliedOperations.every(operation => operation.applied);
+    const outputArtifact = pass ? await fileArtifact(output) : null;
+    if (!pass) await rm(output, { force: true });
+    const receipt = xlsxApplyReceipt.parse({
+      schema: 'tiwater.office.xlsx-apply-receipt/v1',
+      pass,
+      input: inputArtifact,
+      operations: operationsArtifact,
+      output: outputArtifact,
+      appliedOperations: edit.appliedOperations,
+    });
+    return {
+      tool: 'xlsx_apply',
+      runtime: commandRuntime(result),
+      receipt: await writeJsonArtifact(receiptOutput, receipt),
+      output: outputArtifact,
+      summary: {
+        pass,
+        operationCount: edit.appliedOperations.length,
+        appliedCount: edit.appliedOperations.filter(operation => operation.applied).length,
+      },
+    };
+  } catch (error) {
+    await rm(output, { force: true });
+    throw error;
+  }
+}
+
 async function xlsxValidate(args) {
   const input = requireString(args.input, 'input');
   const result = await runXlsxValidateCandidateChain(['validate', input]);

package/package.json

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