@tiwater/office-mcp 0.6.0 → 0.8.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.
@@ -34,4 +34,5 @@ artifact. MCP returns only the artifact path, hash, and byte count.
 Template-migration choice artifacts are opaque evidence. Query the same current
 source and baseline through `docx_query_migration_choices` to page unresolved
 sources, request targets compatible with one business action, or inspect cleanup
-targets.
+targets. Compatible targets stay pageable and are shown in current text and
+local document-context order; the tool does not choose the business mapping.

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',
@@ -74,7 +79,7 @@ const templateMigrationInput = z.object({
   baseline: pathInput.describe('Path to the selected current baseline DOCX.'),
   output: pathInput.describe('Path to the migrated output DOCX.'),
   receiptOutput: pathInput.describe('New JSON receipt artifact path. Existing files are never overwritten.'),
-  choices: z.array(migrationChoiceInput).describe('Exactly one business choice for every source id returned by docx_list_migration_choices.'),
+  choices: z.array(migrationChoiceInput).describe('Exactly one business choice for every source id: place-content writes the source fact; keep-template-content or keep-template-label preserves the matching baseline-owned content or label; select-template-option carries an option identity; exclude-source requires declared exclusion; review-source is limited to genuine local ambiguity.'),
   templateCleanup: z.array(templateCleanupInput).optional().describe('Optional baseline-owned placeholders or example rows to clear.'),
 }).strict();
 
@@ -136,6 +141,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,
@@ -194,7 +235,7 @@ const migrationChoiceQueryInput = z.discriminatedUnion('view', [
     ...migrationQueryDocuments,
     view: z.literal('targets'),
     sourceChoiceId: z.string().trim().min(1).describe('Opaque current source id returned by the sources view.'),
-    action: migrationTargetAction.describe('Business action whose technically compatible current baseline targets are requested.'),
+    action: migrationTargetAction.describe('Business action: place-content writes the current source fact; keep-template-content keeps baseline-owned fixed content; keep-template-label keeps the baseline label for the same source meaning; select-template-option carries a selected source option into the matching baseline option.'),
     text: z.string().trim().min(1).optional().describe('Optional literal case-insensitive text to find in target visible text or context.'),
     offset: boundedOffset,
     limit: boundedLimit,
@@ -264,7 +305,7 @@ const tools = [
   },
   {
     name: 'docx_query_migration_choices',
-    description: 'Query current template-migration alternatives without reading the catalog artifact. Page unresolved sources, request provider-compatible targets for one source and business action, or inspect cleanup targets. This tool does not rank, recommend, or make a business choice.',
+    description: 'Query current template-migration alternatives without reading the catalog artifact. Page unresolved sources, request provider-compatible targets for one source and business action, or inspect cleanup targets. Target results are ordered by literal and local document-context relevance; that order helps discovery but does not make the business choice.',
     inputSchema: migrationChoiceQueryInput,
     outputSchema: migrationChoiceQueryOutput,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -291,13 +332,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 +339,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.',
@@ -438,39 +483,147 @@ async function docxQueryMigrationChoices(args) {
     branch = migrationTargetBranch(action, source.kind);
   }
 
-  const targetResult = await runJsonCandidateChain(docxCandidates, [
-    'find-template-migration-targets',
+  const targetResult = await loadMigrationTargets({
     sourcePath,
     baselinePath,
     sourceChoiceId,
     branch,
-    args.text ?? '-',
-    String(offset),
-    String(limit),
-  ]);
-  const targetPage = migrationTargetPage.parse(targetResult.json);
-  if (targetPage.sourceChoiceId !== (args.view === 'cleanup' ? null : sourceChoiceId) || targetPage.branch !== branch) {
-    throw new Error('Migration target page identity does not match the requested current source and action');
-  }
+    text: args.text,
+  });
   const catalogTargets = new Map(catalog.targets.map(item => [item.id, item]));
-  for (const target of targetPage.targets) {
+  for (const target of targetResult.targets) {
     const current = catalogTargets.get(target.id);
     if (!current || !isDeepStrictEqual(current, target)) {
       throw new Error(`Migration target ${target.id} is not bound to the current catalog`);
     }
   }
+  const catalogOrder = new Map(catalog.targets.map((item, index) => [item.id, index]));
+  const orderedTargets = source
+    ? [...targetResult.targets].sort((left, right) => {
+      const relevance = compareRelevance(
+        migrationChoiceRelevance(source, right),
+        migrationChoiceRelevance(source, left));
+      return relevance || catalogOrder.get(left.id) - catalogOrder.get(right.id);
+    })
+    : [...targetResult.targets].sort((left, right) => catalogOrder.get(left.id) - catalogOrder.get(right.id));
+  const items = orderedTargets.slice(offset, offset + limit);
   return migrationQueryResult({
-    runtime: commandRuntime(targetResult),
+    runtime: targetResult.runtime,
     catalog,
     view: args.view,
     action,
     source,
-    items: targetPage.targets,
-    offset: targetPage.offset,
-    total: targetPage.total,
+    items,
+    offset,
+    total: orderedTargets.length,
   });
 }
 
+async function loadMigrationTargets({ sourcePath, baselinePath, sourceChoiceId, branch, text }) {
+  const targets = [];
+  let offset = 0;
+  let total = null;
+  let runtime = null;
+  do {
+    const result = await runJsonCandidateChain(docxCandidates, [
+      'find-template-migration-targets',
+      sourcePath,
+      baselinePath,
+      sourceChoiceId,
+      branch,
+      text ?? '-',
+      String(offset),
+      '100',
+    ]);
+    const page = migrationTargetPage.parse(result.json);
+    if (page.sourceChoiceId !== (sourceChoiceId === '-' ? null : sourceChoiceId) || page.branch !== branch) {
+      throw new Error('Migration target page identity does not match the requested current source and action');
+    }
+    if (total !== null && page.total !== total) {
+      throw new Error('Migration target page total changed while reading current alternatives');
+    }
+    if (page.offset !== offset || page.targets.length === 0 && offset < page.total) {
+      throw new Error('Migration target pagination did not advance');
+    }
+    runtime ??= commandRuntime(result);
+    total = page.total;
+    targets.push(...page.targets);
+    offset += page.targets.length;
+  } while (offset < total);
+  return { runtime, targets };
+}
+
+function migrationChoiceRelevance(source, target) {
+  const sourceContext = source.context ?? {};
+  const targetContext = target.context ?? {};
+  const sourceRows = sourceContext.sameRowTexts ?? [];
+  const targetRows = targetContext.sameRowTexts ?? [];
+  const sourceHeaders = sourceContext.tableHeaderTexts ?? [];
+  const targetHeaders = targetContext.tableHeaderTexts ?? [];
+  const mainText = textSimilarity(source.text, target.text);
+  const tableIdentity = Math.max(
+    textSimilarity(sourceContext.columnHeaderText, targetContext.columnHeaderText),
+    maximumPairSimilarity(sourceHeaders, targetHeaders));
+  const neighborhood = Math.max(
+    textSimilarity(sourceContext.previousText, targetContext.previousText),
+    textSimilarity(sourceContext.nextText, targetContext.nextText),
+    maximumPairSimilarity(sourceRows, targetRows),
+    maximumPairSimilarity([source.text], targetRows),
+    maximumPairSimilarity(sourceRows, [target.text]));
+  return source.kind === 'table-cell' && target.kind === 'table-cell'
+    ? [tableIdentity, mainText, neighborhood]
+    : [mainText, neighborhood, tableIdentity];
+}
+
+function compareRelevance(left, right) {
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+}
+
+function maximumPairSimilarity(leftValues, rightValues) {
+  let maximum = 0;
+  for (const left of leftValues ?? []) {
+    for (const right of rightValues ?? []) {
+      maximum = Math.max(maximum, textSimilarity(left, right));
+    }
+  }
+  return maximum;
+}
+
+function textSimilarity(leftValue, rightValue) {
+  const left = normalizeSearchText(leftValue);
+  const right = normalizeSearchText(rightValue);
+  if (!left || !right) return 0;
+  if (left === right) return 1;
+  if (Math.min(left.length, right.length) >= 3 && (left.includes(right) || right.includes(left))) {
+    return Math.min(left.length, right.length) / Math.max(left.length, right.length);
+  }
+  const leftPairs = characterPairs(left);
+  const rightPairs = characterPairs(right);
+  if (leftPairs.size === 0 || rightPairs.size === 0) return 0;
+  let shared = 0;
+  for (const pair of leftPairs) if (rightPairs.has(pair)) shared += 1;
+  return 2 * shared / (leftPairs.size + rightPairs.size);
+}
+
+function normalizeSearchText(value) {
+  return typeof value === 'string'
+    ? value.normalize('NFKC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '')
+    : '';
+}
+
+function characterPairs(value) {
+  const characters = [...value];
+  if (characters.length < 2) return new Set(value ? [value] : []);
+  const pairs = new Set();
+  for (let index = 0; index + 1 < characters.length; index += 1) {
+    pairs.add(characters[index] + characters[index + 1]);
+  }
+  return pairs;
+}
+
 function migrationTargetBranch(action, sourceKind) {
   if (action === 'place-content') return sourceKind === 'media' ? 'copy-media' : 'copy-text';
   if (action === 'keep-template-content') return 'retain-target';
@@ -550,13 +703,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]);
@@ -567,6 +713,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']);
@@ -629,6 +833,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.6.0",
+  "version": "0.8.0",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",