@tiwater/office-mcp 0.5.0 → 0.7.0

package/office/README.md

@@ -31,3 +31,8 @@ The official MCP SDK derives the schemas advertised to clients and validates
 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.
+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. 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

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, 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';
 import * as z from 'zod/v4';
@@ -73,7 +74,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();
 
@@ -156,29 +157,64 @@ const migrationQueryPage = z.object({
   hasMore: z.boolean(),
 }).strict();
 
+const migrationTargetPage = z.object({
+  schema: z.string(),
+  pass: z.boolean(),
+  sourceChoiceId: z.string().nullable(),
+  branch: z.string(),
+  offset: z.number().int().nonnegative(),
+  limit: z.number().int().positive(),
+  total: z.number().int().nonnegative(),
+  targets: z.array(migrationChoiceOutput),
+}).strict();
+
+const migrationTargetAction = z.enum([
+  'place-content',
+  'keep-template-content',
+  'keep-template-label',
+  'select-template-option',
+]);
+
+const migrationQueryDocuments = {
+  source: pathInput.describe('Path to the current source DOCX used by docx_list_migration_choices.'),
+  baseline: pathInput.describe('Path to the same selected current baseline DOCX used by docx_list_migration_choices.'),
+};
+
+const boundedOffset = z.number().int().nonnegative().optional().describe('Zero-based result offset. Defaults to 0.');
+const boundedLimit = z.number().int().min(1).max(10).optional().describe('Maximum results to return. Defaults to 10 and cannot exceed 10.');
+
 const migrationChoiceQueryInput = z.discriminatedUnion('view', [
   z.object({
-    catalog: pathInput.describe('Path returned by docx_list_migration_choices.'),
+    ...migrationQueryDocuments,
     view: z.literal('sources'),
-    offset: z.number().int().nonnegative().optional(),
-    limit: z.number().int().min(1).max(10).optional(),
+    offset: boundedOffset,
+    limit: boundedLimit,
   }).strict(),
   z.object({
-    catalog: pathInput.describe('Path returned by docx_list_migration_choices.'),
+    ...migrationQueryDocuments,
     view: z.literal('targets'),
-    sourceChoiceId: z.string().trim().min(1),
-    text: z.string().trim().min(1).optional().describe('Literal case-insensitive text to find in target text or visible context.'),
-    kinds: z.array(z.string().trim().min(1)).min(1).optional(),
-    scopes: z.array(z.string().trim().min(1)).min(1).optional(),
-    offset: z.number().int().nonnegative().optional(),
-    limit: z.number().int().min(1).max(10).optional(),
+    sourceChoiceId: z.string().trim().min(1).describe('Opaque current source id returned by the sources view.'),
+    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,
+  }).strict(),
+  z.object({
+    ...migrationQueryDocuments,
+    view: z.literal('cleanup'),
+    text: z.string().trim().min(1).optional().describe('Optional literal case-insensitive text to find in cleanup target visible text or context.'),
+    offset: boundedOffset,
+    limit: boundedLimit,
   }).strict(),
 ]);
 
 const migrationChoiceQueryOutput = z.object({
   tool: z.literal('docx_query_migration_choices'),
-  catalogSha256: z.string().regex(/^[0-9a-f]{64}$/),
-  view: z.enum(['sources', 'targets']),
+  runtime: runtimeIdentity,
+  sourceSha256: z.string(),
+  baselineSha256: z.string(),
+  view: z.enum(['sources', 'targets', 'cleanup']),
+  action: migrationTargetAction.nullable(),
   source: migrationChoiceOutput.nullable(),
   items: z.array(migrationChoiceOutput),
   page: migrationQueryPage,
@@ -217,7 +253,7 @@ const tools = [
   },
   {
     name: 'docx_list_migration_choices',
-    description: 'Write every current source item that still needs a business choice and the selectable current baseline targets to a run-local JSON artifact. Returns only artifact metadata and counts; it does not recommend a choice.',
+    description: 'Write every current source item that still needs a business choice and the selectable current baseline targets to an opaque run-local evidence artifact. Use docx_query_migration_choices with the same source and baseline to inspect bounded alternatives; do not parse the artifact.',
     inputSchema: z.object({
       source: pathInput.describe('Path to the current source DOCX.'),
       baseline: pathInput.describe('Path to the selected current baseline DOCX.'),
@@ -228,7 +264,7 @@ const tools = [
   },
   {
     name: 'docx_query_migration_choices',
-    description: 'Read one bounded page from a migration-choice catalog. List source choices, or inspect targets for one source using literal text, kind, and scope filters. This tool does not 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 },
@@ -363,61 +399,213 @@ async function docxListMigrationChoices(args) {
 }
 
 async function docxQueryMigrationChoices(args) {
-  const catalogPath = requireString(args.catalog, 'catalog');
-  const bytes = await readFile(catalogPath);
-  const catalog = migrationCatalog.parse(JSON.parse(bytes.toString('utf8')));
+  const sourcePath = requireString(args.source, 'source');
+  const baselinePath = requireString(args.baseline, 'baseline');
   const offset = args.offset ?? 0;
   const limit = args.limit ?? 10;
-  let source = null;
-  let matches;
+  const catalogResult = await runJsonCandidateChain(docxCandidates, ['list-template-migration-choices', sourcePath, baselinePath]);
+  const catalog = migrationCatalog.parse(catalogResult.json);
 
   if (args.view === 'sources') {
-    matches = catalog.sources;
+    return migrationQueryResult({
+      runtime: commandRuntime(catalogResult),
+      catalog,
+      view: 'sources',
+      action: null,
+      source: null,
+      items: catalog.sources.slice(offset, offset + limit),
+      offset,
+      total: catalog.sources.length,
+    });
+  }
+
+  let source = null;
+  let action = null;
+  let branch;
+  let sourceChoiceId = '-';
+  if (args.view === 'cleanup') {
+    branch = 'baseline-clear';
   } else {
     source = catalog.sources.find(item => item.id === args.sourceChoiceId) ?? null;
     if (!source) {
       throw Object.assign(new Error(`Unknown sourceChoiceId: ${args.sourceChoiceId}`), { code: -32602 });
     }
-    const kinds = args.kinds ? new Set(args.kinds) : null;
-    const scopes = args.scopes ? new Set(args.scopes) : null;
-    const textQuery = args.text?.toLocaleLowerCase();
-    matches = catalog.targets.filter(item =>
-      (!kinds || kinds.has(item.kind)) &&
-      (!scopes || scopes.has(item.scope)) &&
-      (!textQuery || migrationChoiceSearchText(item).includes(textQuery)));
+    action = args.action;
+    if (!source.allowedActions.includes(action)) {
+      throw Object.assign(new Error(`Action ${action} is not allowed for ${source.id}`), { code: -32602 });
+    }
+    sourceChoiceId = source.id;
+    branch = migrationTargetBranch(action, source.kind);
+  }
+
+  const targetResult = await loadMigrationTargets({
+    sourcePath,
+    baselinePath,
+    sourceChoiceId,
+    branch,
+    text: args.text,
+  });
+  const catalogTargets = new Map(catalog.targets.map(item => [item.id, item]));
+  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: targetResult.runtime,
+    catalog,
+    view: args.view,
+    action,
+    source,
+    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;
+}
 
-  const items = matches.slice(offset, offset + limit);
+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';
+  if (action === 'keep-template-label') return 'retain-target-label';
+  if (action === 'select-template-option') return 'choice-selection';
+  throw new Error(`Unsupported migration target action: ${action}`);
+}
+
+function migrationQueryResult({ runtime, catalog, view, action, source, items, offset, total }) {
   return {
     tool: 'docx_query_migration_choices',
-    catalogSha256: createHash('sha256').update(bytes).digest('hex'),
-    view: args.view,
+    runtime,
+    sourceSha256: catalog.sourceSha256,
+    baselineSha256: catalog.baselineSha256,
+    view,
+    action,
     source,
     items,
     page: {
       offset,
       returned: items.length,
-      total: matches.length,
-      hasMore: offset + items.length < matches.length,
+      total,
+      hasMore: offset + items.length < total,
     },
   };
 }
 
-function migrationChoiceSearchText(choice) {
-  return collectVisibleStrings({ text: choice.text, context: choice.context })
-    .join('\n')
-    .toLocaleLowerCase();
-}
-
-function collectVisibleStrings(value, fieldName = '') {
-  if (typeof value === 'string') return /text/i.test(fieldName) ? [value] : [];
-  if (Array.isArray(value)) return value.flatMap(item => collectVisibleStrings(item, fieldName));
-  if (value && typeof value === 'object') {
-    return Object.entries(value).flatMap(([key, item]) => collectVisibleStrings(item, key));
-  }
-  return [];
-}
-
 async function docxMigrateTemplate(args) {
   return runTemplateMigrationCommand('docx_migrate_template', 'migrate-template', args);
 }

package/package.json

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