@tiwater/office-mcp 0.7.0 → 0.9.0

package/office/README.md

@@ -10,8 +10,8 @@ Shared stdio MCP server for Office document workflows.
 - `docx_migrate_template`
 - `docx_verify_migration`
 - `docx_compare`
-- `docx_validate_template_transform`
 - `docx_export_json`
+- `office_render_pdf`
 - `xlsx_inspect`
 - `xlsx_export_json`
 - `xlsx_validate`
@@ -23,9 +23,9 @@ 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.
 
-The server invokes published `tiwater-docx`, `tiwater-xlsx`, and
-`tiwater-pptx` commands from `PATH`. It does not require a source checkout or
-fall back to local projects.
+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.
 
 The official MCP SDK derives the schemas advertised to clients and validates
 tool arguments and structured results before they cross the protocol boundary.

package/office/index.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+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';
@@ -30,6 +31,10 @@ const pptxCandidates = [
   commandCandidate('tiwater-pptx', [], { cwd: invocationCwd }),
 ];
 
+const convertCandidates = [
+  commandCandidate('tiwater-convert', [], { cwd: invocationCwd }),
+];
+
 const pathInput = z.string().trim().min(1);
 const migrationAction = z.enum([
   'place-content',
@@ -51,7 +56,6 @@ const migrationChoiceInput = z.object({
   sourceChoiceId: z.string().trim().min(1),
   action: migrationAction,
   targetChoiceId: z.string().trim().min(1).optional(),
-  cardinality: z.enum(['one', 'all']).optional(),
 }).strict().superRefine((choice, context) => {
   if (targetActions.has(choice.action) && !choice.targetChoiceId) {
     context.addIssue({ code: 'custom', path: ['targetChoiceId'], message: `${choice.action} requires targetChoiceId` });
@@ -59,9 +63,6 @@ const migrationChoiceInput = z.object({
   if (terminalActions.has(choice.action) && choice.targetChoiceId) {
     context.addIssue({ code: 'custom', path: ['targetChoiceId'], message: `${choice.action} forbids targetChoiceId` });
   }
-  if (choice.cardinality === 'all' && !terminalActions.has(choice.action)) {
-    context.addIssue({ code: 'custom', path: ['cardinality'], message: 'cardinality all is limited to terminal actions' });
-  }
 });
 
 const templateCleanupInput = z.object({
@@ -136,6 +137,42 @@ const artifact = z.object({
   bytes: z.number().int().nonnegative(),
 }).strict();
 
+const renderFileIdentity = z.object({
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  size_bytes: z.number().int().positive(),
+}).strict();
+const nativeRenderReceipt = z.object({
+  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.enum(['doc', 'docx', 'odt', 'rtf', 'xls', 'xlsx', 'ods', 'ppt', 'pptx', 'odp']),
+  target_format: z.literal('pdf'),
+  version: z.string(),
+  backend: z.enum(['wps', 'et', 'wpp']),
+  fallback_reason: z.null(),
+  page_count: z.number().int().positive(),
+  native_render_provenance: z.object({
+    schema: z.literal('tiwater.convert-native-render-provenance/v1'),
+    backend: z.enum(['wps', 'et', 'wpp']),
+    input: renderFileIdentity,
+    output: renderFileIdentity,
+    page_count: z.number().int().positive(),
+  }).passthrough(),
+}).passthrough();
+const nativeRenderOutput = z.object({
+  tool: z.literal('office_render_pdf'),
+  runtime: runtimeIdentity,
+  pdf: artifact,
+  receipt: artifact,
+  summary: z.object({
+    sourceFormat: z.string(),
+    backend: z.enum(['wps', 'et', 'wpp']),
+    pageCount: z.number().int().positive(),
+  }).strict(),
+}).strict();
+
 const migrationCatalogOutput = z.object({
   tool: z.literal('docx_list_migration_choices'),
   runtime: runtimeIdentity,
@@ -291,13 +328,6 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true },
     handler: docxCompare,
   },
-  {
-    name: 'docx_validate_template_transform',
-    description: 'Validate whether a source DOCX template and target DOCX template are structurally compatible.',
-    inputSchema: z.object({ sourceTemplate: pathInput, targetTemplate: pathInput }).strict(),
-    annotations: { readOnlyHint: true, idempotentHint: true },
-    handler: docxValidateTemplateTransform,
-  },
   {
     name: 'docx_export_json',
     description: 'Export DOCX body content to a new JSON artifact without returning the full document through MCP.',
@@ -305,6 +335,17 @@ const tools = [
     outputSchema: artifactOutput('docx_export_json'),
     handler: docxExportJson,
   },
+  {
+    name: 'office_render_pdf',
+    description: 'Render a current Office document to PDF with its required native WPS backend and write the complete provider receipt as evidence. The input extension selects Writer, Spreadsheets, or Presentation; fallback rendering is rejected.',
+    inputSchema: z.object({
+      input: pathInput.describe('Path to the current Office document.'),
+      output: pathInput.describe('New PDF output path. Existing files are never overwritten.'),
+      receiptOutput: pathInput.describe('New JSON receipt path. Existing files are never overwritten.'),
+    }).strict(),
+    outputSchema: nativeRenderOutput,
+    handler: officeRenderPdf,
+  },
   {
     name: 'xlsx_inspect',
     description: 'Inspect an XLSX workbook and write one JSON observation containing workbook structure, exported values, formulas, styles, merged ranges, and conversion evidence.',
@@ -614,6 +655,32 @@ async function docxVerifyMigration(args) {
   return runTemplateMigrationCommand('docx_verify_migration', 'verify-template-migration', args);
 }
 
+function invalidMigrationInput(message) {
+  return Object.assign(new Error(message), { code: -32602 });
+}
+
+function completeMigrationChoices(catalog, choices) {
+  const sources = new Map(catalog.sources.map(source => [source.id, source]));
+  const seen = new Set();
+  const completed = choices.map(choice => {
+    const source = sources.get(choice.sourceChoiceId);
+    if (!source) throw invalidMigrationInput(`unknown migration source id: ${choice.sourceChoiceId}`);
+    if (seen.has(choice.sourceChoiceId)) throw invalidMigrationInput(`duplicate migration source id: ${choice.sourceChoiceId}`);
+    seen.add(choice.sourceChoiceId);
+    if (!source.allowedActions.includes(choice.action)) {
+      throw invalidMigrationInput(`migration action ${choice.action} is not allowed for source id: ${choice.sourceChoiceId}`);
+    }
+    return source.requiredCardinality === 'all'
+      ? { ...choice, cardinality: 'all' }
+      : choice;
+  });
+  const missing = [...sources.keys()].filter(sourceChoiceId => !seen.has(sourceChoiceId));
+  if (missing.length > 0) {
+    throw invalidMigrationInput(`migration choices must cover every source id; missing ${missing.length}`);
+  }
+  return completed;
+}
+
 async function runTemplateMigrationCommand(tool, command, args) {
   const source = requireString(args.source, 'source');
   const baseline = requireString(args.baseline, 'baseline');
@@ -621,9 +688,11 @@ async function runTemplateMigrationCommand(tool, command, args) {
   if (!Array.isArray(args.choices)) {
     throw Object.assign(new Error('choices must be an array'), { code: -32602 });
   }
+  const catalogResult = await runJsonCandidateChain(docxCandidates, ['list-template-migration-choices', source, baseline]);
+  const catalog = migrationCatalog.parse(catalogResult.json);
   const payload = {
     schema: 'tiwater.docx.template-migration-business-choices/v1',
-    choices: args.choices,
+    choices: completeMigrationChoices(catalog, args.choices),
     ...(Array.isArray(args.templateCleanup) ? { templateCleanup: args.templateCleanup } : {}),
   };
   return withTempJsonFile(payload, async choicesPath => {
@@ -631,6 +700,10 @@ async function runTemplateMigrationCommand(tool, command, args) {
       docxCandidates,
       [command, source, baseline, choicesPath, output],
       { allowedExitCodes: [0, 1] });
+    if (result.json === null) {
+      const detail = result.stderr.trim() || result.stdout.trim() || 'no diagnostic output';
+      throw new Error(`${result.command} ${command} returned no JSON receipt (exit ${result.code}): ${detail}`);
+    }
     const receipt = migrationReceipt.parse(result.json);
     return {
       tool,
@@ -658,13 +731,6 @@ async function docxCompare(args) {
   return { tool: 'docx_compare', runtime: commandRuntime(result), report: result.json };
 }
 
-async function docxValidateTemplateTransform(args) {
-  const sourceTemplate = requireString(args.sourceTemplate, 'sourceTemplate');
-  const targetTemplate = requireString(args.targetTemplate, 'targetTemplate');
-  const result = await runJsonCandidateChain(docxCandidates, ['validate-template-transform', sourceTemplate, targetTemplate, '--json']);
-  return { tool: 'docx_validate_template_transform', runtime: commandRuntime(result), report: result.json };
-}
-
 async function docxExportJson(args) {
   const input = requireString(args.input, 'input');
   const result = await runJsonCandidateChain(docxCandidates, ['export-json', input]);
@@ -675,6 +741,64 @@ async function docxExportJson(args) {
   };
 }
 
+async function officeRenderPdf(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'));
+  const sourceFormat = path.extname(input).slice(1).toLowerCase();
+  const backend = nativeRenderBackend(sourceFormat);
+  if (path.extname(output).toLowerCase() !== '.pdf') {
+    throw Object.assign(new Error(`Office render output must be a PDF: ${output}`), { code: -32602 });
+  }
+  const inputArtifact = await fileArtifact(input);
+  await requireNewFile(output, 'output');
+  await requireNewFile(receiptOutput, 'receiptOutput');
+  await mkdir(path.dirname(output), { recursive: true });
+  try {
+    const result = await runJsonCandidateChain(
+      convertCandidates,
+      [`${sourceFormat}-to-pdf`, input, output],
+      { env: { TIWATER_OFFICE_PDF_BACKEND: backend } });
+    const receipt = nativeRenderReceipt.parse(result.json);
+    const pdf = await fileArtifact(output);
+    if (path.resolve(receipt.input) !== input
+        || path.resolve(receipt.output) !== output
+        || receipt.source_format !== sourceFormat
+        || receipt.backend !== backend
+        || receipt.native_render_provenance.backend !== backend
+        || receipt.page_count !== receipt.native_render_provenance.page_count
+        || receipt.input_sha256 !== inputArtifact.sha256
+        || receipt.native_render_provenance.input.sha256 !== inputArtifact.sha256
+        || receipt.native_render_provenance.input.size_bytes !== inputArtifact.bytes
+        || receipt.output_sha256 !== pdf.sha256
+        || receipt.native_render_provenance.output.sha256 !== pdf.sha256
+        || receipt.native_render_provenance.output.size_bytes !== pdf.bytes) {
+      throw new Error('Native Office render receipt is not bound to the current input and output');
+    }
+    return {
+      tool: 'office_render_pdf',
+      runtime: commandRuntime(result),
+      pdf,
+      receipt: await writeJsonArtifact(receiptOutput, receipt),
+      summary: {
+        sourceFormat,
+        backend,
+        pageCount: receipt.page_count,
+      },
+    };
+  } catch (error) {
+    await rm(output, { force: true });
+    throw error;
+  }
+}
+
+function nativeRenderBackend(sourceFormat) {
+  if (['doc', 'docx', 'odt', 'rtf'].includes(sourceFormat)) return 'wps';
+  if (['xls', 'xlsx', 'ods'].includes(sourceFormat)) return 'et';
+  if (['ppt', 'pptx', 'odp'].includes(sourceFormat)) return 'wpp';
+  throw Object.assign(new Error(`Unsupported Office render input: .${sourceFormat || '(none)'}`), { code: -32602 });
+}
+
 async function xlsxInspect(args) {
   const input = requireString(args.input, 'input');
   const result = await runJsonCandidateChain(xlsxCandidates, ['inspect', input, '--json']);
@@ -737,6 +861,29 @@ async function writeJsonArtifact(output, payload) {
   };
 }
 
+async function fileArtifact(filePath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(filePath)) {
+    hash.update(chunk);
+  }
+  const file = await stat(filePath);
+  return {
+    path: path.resolve(filePath),
+    sha256: hash.digest('hex'),
+    bytes: file.size,
+  };
+}
+
+async function requireNewFile(filePath, label) {
+  try {
+    await stat(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw error;
+  }
+  throw Object.assign(new Error(`${label} already exists: ${filePath}`), { code: -32602 });
+}
+
 function commandRuntime(result) {
   return {
     command: result.command,

package/package.json

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