@tiwater/office-mcp 0.10.1 → 0.11.1

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,7 +24,7 @@ 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.10 requires these minimum published runtimes on `PATH`:
+Office MCP 0.11 requires these minimum published runtimes on `PATH`:
 
 | Command | Package | Minimum version |
 | --- | --- | --- |
@@ -41,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

@@ -3,7 +3,6 @@ import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 import { isDeepStrictEqual } from 'node:util';
 import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
@@ -138,6 +137,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 +390,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,9 +1005,59 @@ 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]);
+  const result = await runJsonCandidateChain(xlsxCandidates, ['validate', input], { allowedExitCodes: [0, 1] });
   return { tool: 'xlsx_validate', runtime: commandRuntime(result), result: result.json };
 }
 
@@ -1030,59 +1124,3 @@ function commandRuntime(result) {
 }
 
 serveStdio(buildServer);
-
-async function runXlsxValidateCandidateChain(args) {
-  const errors = [];
-  for (const candidate of xlsxCandidates) {
-    try {
-      const result = await runValidationCommand(candidate, args);
-      const text = result.stdout.trim();
-      if (!text) return { ...result, json: null };
-      try {
-        return { ...result, json: JSON.parse(text) };
-      } catch {
-        if (result.code !== 0) {
-          errors.push(`${candidate.command}: validate did not return JSON`);
-          continue;
-        }
-        throw new Error(`Expected JSON output but received: ${text.slice(0, 300)}${text.length > 300 ? '…' : ''}`);
-      }
-    } catch (error) {
-      if (error?.code === 'ENOENT') {
-        errors.push(`${candidate.command}: not found`);
-        continue;
-      }
-      throw error;
-    }
-  }
-  throw new Error(`No runnable command candidate succeeded. ${errors.join('; ')}`);
-}
-
-async function runValidationCommand(candidate, args) {
-  const env = { ...process.env, ...(candidate.env || {}) };
-  const cwd = candidate.cwd || process.cwd();
-  const commandArgs = [...(candidate.argsPrefix || []), ...args];
-
-  return await new Promise((resolve, reject) => {
-    const child = spawn(candidate.command, commandArgs, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout.on('data', chunk => {
-      stdout += chunk.toString();
-    });
-
-    child.stderr.on('data', chunk => {
-      stderr += chunk.toString();
-    });
-
-    child.on('error', reject);
-    child.on('close', code => {
-      if (code === 0 || code === 1) {
-        resolve({ code, stdout, stderr, command: candidate.command, args: commandArgs, cwd });
-        return;
-      }
-      reject(new Error(`${candidate.command} ${commandArgs.join(' ')} failed with exit code ${code}\n${stderr || stdout}`));
-    });
-  });
-}

package/package.json

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