@tiwater/office-mcp 0.11.0 → 0.12.0

package/office/README.md

@@ -18,19 +18,21 @@ Shared stdio MCP server for Office document workflows.
 - `xlsx_validate`
 - `pptx_inspect`
 - `pptx_export_json`
+- `pptx_apply_template`
+- `pptx_apply_format`
 
 ## Run
 
 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`:
+Office MCP 0.12 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-pptx` | NuGet `tiwater.pptx.cli` | 0.3.1 |
 | `tiwater-convert` | NuGet `tiwater.convert.cli` | 0.9.22 |
 
 The server invokes published `tiwater-docx`, `tiwater-xlsx`,
@@ -52,6 +54,21 @@ 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.
 
+## Presentation editing
+
+`pptx_apply_template` and `pptx_apply_format` are orthogonal execution
+operations. The first applies a deterministic template plan to a current
+presentation and selected current template. The second applies deterministic
+format operations to a current presentation. Both bind their inputs, created
+output, and complete runtime result by path and content hash. They do not select
+templates, interpret scenario knowledge, or derive business content, slide
+mappings, geometry, coordinates, or formatting decisions.
+
+Callers apply a template first, inspect and validate that intermediate result,
+then build and apply formatting against the intermediate presentation. Final
+inspection, independent readback, native rendering, and delivery closure remain
+separate operations.
+
 ## Template migration
 
 Template migration separates business choice from document mechanics:

package/office/contracts/tiwater.office.pptx-format-apply-receipt-v1.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office.pptx-format-apply-receipt/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "pass", "input", "operations", "output", "providerResult"],
+  "properties": {
+    "schema": { "const": "tiwater.office.pptx-format-apply-receipt/v1" },
+    "pass": { "type": "boolean" },
+    "input": { "$ref": "#/$defs/artifact" },
+    "operations": { "$ref": "#/$defs/artifact" },
+    "output": { "oneOf": [{ "$ref": "#/$defs/artifact" }, { "type": "null" }] },
+    "providerResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "output", "operationCount", "changedCount", "changes", "issues"],
+      "properties": {
+        "input": { "type": "string", "minLength": 1 },
+        "output": { "type": "string", "minLength": 1 },
+        "operationCount": { "type": "integer", "minimum": 0 },
+        "changedCount": { "type": "integer", "minimum": 0 },
+        "changes": { "type": "array", "items": { "$ref": "#/$defs/change" } },
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } }
+      }
+    }
+  },
+  "$defs": {
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256", "bytes"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slideNumber", "shapeId", "runIndex", "properties"],
+      "properties": {
+        "slideNumber": { "type": "integer", "minimum": 1 },
+        "shapeId": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "runIndex": { "type": "integer", "minimum": 0 },
+        "properties": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slideNumber", "shapeId", "runIndex", "message"],
+      "properties": {
+        "slideNumber": { "type": "integer", "minimum": 1 },
+        "shapeId": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "runIndex": { "type": "integer", "minimum": 0 },
+        "message": { "type": "string" }
+      }
+    }
+  }
+}

package/office/contracts/tiwater.office.pptx-template-apply-receipt-v1.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office.pptx-template-apply-receipt/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "pass", "input", "template", "plan", "output", "providerResult"],
+  "properties": {
+    "schema": { "const": "tiwater.office.pptx-template-apply-receipt/v1" },
+    "pass": { "type": "boolean" },
+    "input": { "$ref": "#/$defs/artifact" },
+    "template": { "$ref": "#/$defs/artifact" },
+    "plan": { "$ref": "#/$defs/artifact" },
+    "output": { "oneOf": [{ "$ref": "#/$defs/artifact" }, { "type": "null" }] },
+    "providerResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "template", "output", "changedSlideCount", "issues", "materializedLayoutShapes", "frozenPlaceholderCount", "removedSystemPlaceholders"],
+      "properties": {
+        "input": { "type": "string", "minLength": 1 },
+        "template": { "type": "string", "minLength": 1 },
+        "output": { "type": "string", "minLength": 1 },
+        "changedSlideCount": { "type": "integer", "minimum": 0 },
+        "issues": { "type": "array", "items": { "$ref": "#/$defs/issue" } },
+        "materializedLayoutShapes": { "type": "array", "items": { "$ref": "#/$defs/materializedShape" } },
+        "frozenPlaceholderCount": { "type": "integer", "minimum": 0 },
+        "removedSystemPlaceholders": { "type": "array", "items": { "$ref": "#/$defs/removedPlaceholder" } }
+      }
+    }
+  },
+  "$defs": {
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256", "bytes"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slideNumber", "message"],
+      "properties": {
+        "slideNumber": { "type": ["integer", "null"], "minimum": 1 },
+        "message": { "type": "string" }
+      }
+    },
+    "materializedShape": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slideNumber", "sourceLayoutPath", "sourceShapeId", "outputShapeId"],
+      "properties": {
+        "slideNumber": { "type": "integer", "minimum": 1 },
+        "sourceLayoutPath": { "type": "string", "minLength": 1 },
+        "sourceShapeId": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "outputShapeId": { "type": "integer", "minimum": 0, "maximum": 4294967295 }
+      }
+    },
+    "removedPlaceholder": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slideNumber", "shapeId", "placeholderType"],
+      "properties": {
+        "slideNumber": { "type": "integer", "minimum": 1 },
+        "shapeId": { "type": "integer", "minimum": 0, "maximum": 4294967295 },
+        "placeholderType": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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';
@@ -171,6 +170,87 @@ const xlsxApplyOutput = z.object({
   }).strict(),
 }).strict();
 
+const pptxTemplateApplyResult = z.object({
+  input: z.string().min(1),
+  template: z.string().min(1),
+  output: z.string().min(1),
+  changedSlideCount: z.number().int().nonnegative(),
+  issues: z.array(z.object({
+    slideNumber: z.number().int().positive().nullable(),
+    message: z.string(),
+  }).strict()),
+  materializedLayoutShapes: z.array(z.object({
+    slideNumber: z.number().int().positive(),
+    sourceLayoutPath: z.string().min(1),
+    sourceShapeId: z.number().int().nonnegative().max(0xffffffff),
+    outputShapeId: z.number().int().nonnegative().max(0xffffffff),
+  }).strict()),
+  frozenPlaceholderCount: z.number().int().nonnegative(),
+  removedSystemPlaceholders: z.array(z.object({
+    slideNumber: z.number().int().positive(),
+    shapeId: z.number().int().nonnegative().max(0xffffffff),
+    placeholderType: z.string().min(1),
+  }).strict()),
+}).strict();
+const pptxFormatApplyResult = z.object({
+  input: z.string().min(1),
+  output: z.string().min(1),
+  operationCount: z.number().int().nonnegative(),
+  changedCount: z.number().int().nonnegative(),
+  changes: z.array(z.object({
+    slideNumber: z.number().int().positive(),
+    shapeId: z.number().int().nonnegative().max(0xffffffff),
+    runIndex: z.number().int().nonnegative(),
+    properties: z.array(z.string()),
+  }).strict()),
+  issues: z.array(z.object({
+    slideNumber: z.number().int().positive(),
+    shapeId: z.number().int().nonnegative().max(0xffffffff),
+    runIndex: z.number().int().nonnegative(),
+    message: z.string(),
+  }).strict()),
+}).strict();
+const pptxTemplateApplyReceipt = z.object({
+  schema: z.literal('tiwater.office.pptx-template-apply-receipt/v1'),
+  pass: z.boolean(),
+  input: artifact,
+  template: artifact,
+  plan: artifact,
+  output: artifact.nullable(),
+  providerResult: pptxTemplateApplyResult,
+}).strict();
+const pptxFormatApplyReceipt = z.object({
+  schema: z.literal('tiwater.office.pptx-format-apply-receipt/v1'),
+  pass: z.boolean(),
+  input: artifact,
+  operations: artifact,
+  output: artifact.nullable(),
+  providerResult: pptxFormatApplyResult,
+}).strict();
+const pptxTemplateApplyOutput = z.object({
+  tool: z.literal('pptx_apply_template'),
+  runtime: runtimeIdentity,
+  receipt: artifact,
+  output: artifact.nullable(),
+  summary: z.object({
+    pass: z.boolean(),
+    changedSlideCount: z.number().int().nonnegative(),
+    issueCount: z.number().int().nonnegative(),
+  }).strict(),
+}).strict();
+const pptxFormatApplyOutput = z.object({
+  tool: z.literal('pptx_apply_format'),
+  runtime: runtimeIdentity,
+  receipt: artifact,
+  output: artifact.nullable(),
+  summary: z.object({
+    pass: z.boolean(),
+    operationCount: z.number().int().nonnegative(),
+    changedCount: z.number().int().nonnegative(),
+    issueCount: z.number().int().nonnegative(),
+  }).strict(),
+}).strict();
+
 const renderFileIdentity = z.object({
   sha256: z.string().regex(/^[a-f0-9]{64}$/),
   size_bytes: z.number().int().positive(),
@@ -424,6 +504,31 @@ const tools = [
     outputSchema: artifactOutput('pptx_export_json'),
     handler: pptxExportJson,
   },
+  {
+    name: 'pptx_apply_template',
+    description: 'Apply one deterministic PPTX template-application plan to a current presentation. This tool executes the published plan; it does not select a template or derive business content, slide mappings, geometry, or formatting decisions.',
+    inputSchema: z.object({
+      input: pathInput.describe('Path to the current source PPTX.'),
+      template: pathInput.describe('Path to the selected current template PPTX.'),
+      plan: pathInput.describe('Path to the deterministic template-application plan artifact.'),
+      output: pathInput.describe('New PPTX output path. Existing files are never overwritten.'),
+      receiptOutput: pathInput.describe('New JSON receipt path. Existing files are never overwritten.'),
+    }).strict(),
+    outputSchema: pptxTemplateApplyOutput,
+    handler: pptxApplyTemplate,
+  },
+  {
+    name: 'pptx_apply_format',
+    description: 'Apply one deterministic PPTX formatting plan to a current presentation. This tool executes published formatting operations; it does not derive values, coordinates, or business decisions.',
+    inputSchema: z.object({
+      input: pathInput.describe('Path to the current PPTX.'),
+      operations: pathInput.describe('Path to the deterministic formatting operations artifact.'),
+      output: pathInput.describe('New PPTX output path. Existing files are never overwritten.'),
+      receiptOutput: pathInput.describe('New JSON receipt path. Existing files are never overwritten.'),
+    }).strict(),
+    outputSchema: pptxFormatApplyOutput,
+    handler: pptxApplyFormat,
+  },
 ];
 
 function buildServer() {
@@ -1058,7 +1163,7 @@ async function xlsxApply(args) {
 
 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 };
 }
 
@@ -1082,6 +1187,81 @@ async function pptxExportJson(args) {
   };
 }
 
+async function pptxApplyTemplate(args) {
+  return pptxApply('pptx_apply_template', args, true);
+}
+
+async function pptxApplyFormat(args) {
+  return pptxApply('pptx_apply_format', args, false);
+}
+
+async function pptxApply(tool, args, templateMode) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  const template = templateMode ? path.resolve(requireString(args.template, 'template')) : null;
+  const plan = path.resolve(requireString(templateMode ? args.plan : args.operations, templateMode ? 'plan' : 'operations'));
+  const output = path.resolve(requireString(args.output, 'output'));
+  const receiptOutput = path.resolve(requireString(args.receiptOutput, 'receiptOutput'));
+  for (const [label, candidate] of [['input', input], ['output', output], ...(template ? [['template', template]] : [])]) {
+    if (path.extname(candidate).toLowerCase() !== '.pptx') {
+      throw Object.assign(new Error(`${label} must use the .pptx extension`), { code: -32602 });
+    }
+  }
+  await requireNewFile(output, 'output');
+  await requireNewFile(receiptOutput, 'receiptOutput');
+  const inputArtifact = await fileArtifact(input);
+  const templateArtifact = template ? await fileArtifact(template) : null;
+  const planArtifact = await fileArtifact(plan);
+  await mkdir(path.dirname(output), { recursive: true });
+  try {
+    const command = templateMode ? 'apply-template' : 'apply-format-edits';
+    const commandArgs = templateMode
+      ? [command, input, template, plan, output]
+      : [command, input, plan, output];
+    const result = await runJsonCandidateChain(pptxCandidates, commandArgs, { allowedExitCodes: [0, 1] });
+    await requireArtifactUnchanged(inputArtifact, 'PPTX apply input');
+    if (templateArtifact) await requireArtifactUnchanged(templateArtifact, 'PPTX apply template');
+    await requireArtifactUnchanged(planArtifact, 'PPTX apply plan');
+    const providerResult = (templateMode ? pptxTemplateApplyResult : pptxFormatApplyResult).parse(result.json);
+    if (path.resolve(providerResult.input) !== input
+        || path.resolve(providerResult.output) !== output
+        || (templateMode && path.resolve(providerResult.template) !== template)) {
+      throw new Error('PPTX apply receipt is not bound to the current inputs and output');
+    }
+    const pass = providerResult.issues.length === 0;
+    const outputArtifact = pass ? await fileArtifact(output) : null;
+    if (!pass) await rm(output, { force: true });
+    const receiptSchema = templateMode ? pptxTemplateApplyReceipt : pptxFormatApplyReceipt;
+    const receipt = receiptSchema.parse({
+      schema: templateMode
+        ? 'tiwater.office.pptx-template-apply-receipt/v1'
+        : 'tiwater.office.pptx-format-apply-receipt/v1',
+      pass,
+      input: inputArtifact,
+      ...(templateMode ? { template: templateArtifact } : {}),
+      ...(templateMode ? { plan: planArtifact } : { operations: planArtifact }),
+      output: outputArtifact,
+      providerResult,
+    });
+    return {
+      tool,
+      runtime: commandRuntime(result),
+      receipt: await writeJsonArtifact(receiptOutput, receipt),
+      output: outputArtifact,
+      summary: templateMode
+        ? { pass, changedSlideCount: providerResult.changedSlideCount, issueCount: providerResult.issues.length }
+        : { pass, operationCount: providerResult.operationCount, changedCount: providerResult.changedCount, issueCount: providerResult.issues.length },
+    };
+  } catch (error) {
+    await rm(output, { force: true });
+    throw error;
+  }
+}
+
+async function requireArtifactUnchanged(expected, label) {
+  const current = await fileArtifact(expected.path);
+  if (!isDeepStrictEqual(current, expected)) throw new Error(`${label} changed during provider execution`);
+}
+
 async function writeJsonArtifact(output, payload) {
   const fullPath = path.resolve(output);
   await mkdir(path.dirname(fullPath), { recursive: true });
@@ -1125,59 +1305,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.11.0",
+  "version": "0.12.0",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,8 @@
   "files": [
     "_shared/tool-runtime.mjs",
     "office/index.mjs",
-    "office/README.md"
+    "office/README.md",
+    "office/contracts/*.schema.json"
   ],
   "scripts": {
     "test": "node --test office/*.test.mjs"
@@ -29,5 +30,8 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "ajv": "8.20.0"
   }
 }