@tiwater/office-mcp 0.4.0 → 0.6.0

package/office/README.md

@@ -6,6 +6,7 @@ Shared stdio MCP server for Office document workflows.
 
 - `docx_inspect`
 - `docx_list_migration_choices`
+- `docx_query_migration_choices`
 - `docx_migrate_template`
 - `docx_verify_migration`
 - `docx_compare`
@@ -30,3 +31,7 @@ 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.

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';
@@ -100,7 +101,17 @@ const migrationCatalog = z.object({
   baselineSha256: z.string(),
   sources: z.array(migrationChoiceOutput),
   targets: z.array(migrationChoiceOutput),
-}).strict();
+}).strict().superRefine((catalog, context) => {
+  for (const key of ['sources', 'targets']) {
+    const seen = new Set();
+    for (const [index, choice] of catalog[key].entries()) {
+      if (seen.has(choice.id)) {
+        context.addIssue({ code: 'custom', path: [key, index, 'id'], message: `duplicate ${key} choice id: ${choice.id}` });
+      }
+      seen.add(choice.id);
+    }
+  }
+});
 
 const migrationReceipt = z.object({
   schema: z.string(),
@@ -139,6 +150,76 @@ const migrationCatalogOutput = z.object({
   }).strict(),
 }).strict();
 
+const migrationQueryPage = z.object({
+  offset: z.number().int().nonnegative(),
+  returned: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+  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({
+    ...migrationQueryDocuments,
+    view: z.literal('sources'),
+    offset: boundedOffset,
+    limit: boundedLimit,
+  }).strict(),
+  z.object({
+    ...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.'),
+    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'),
+  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,
+}).strict();
+
 function migrationReceiptOutput(tool) {
   return z.object({
     tool: z.literal(tool),
@@ -172,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.'),
@@ -181,6 +262,14 @@ const tools = [
     outputSchema: migrationCatalogOutput,
     handler: docxListMigrationChoices,
   },
+  {
+    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.',
+    inputSchema: migrationChoiceQueryInput,
+    outputSchema: migrationChoiceQueryOutput,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    handler: docxQueryMigrationChoices,
+  },
   {
     name: 'docx_migrate_template',
     description: 'Migrate a current DOCX into the selected baseline from one complete batch of business choices. Choices reference only opaque ids returned by docx_list_migration_choices; the tool derives all document values, coordinates, plans, and edits.',
@@ -309,6 +398,106 @@ async function docxListMigrationChoices(args) {
   };
 }
 
+async function docxQueryMigrationChoices(args) {
+  const sourcePath = requireString(args.source, 'source');
+  const baselinePath = requireString(args.baseline, 'baseline');
+  const offset = args.offset ?? 0;
+  const limit = args.limit ?? 10;
+  const catalogResult = await runJsonCandidateChain(docxCandidates, ['list-template-migration-choices', sourcePath, baselinePath]);
+  const catalog = migrationCatalog.parse(catalogResult.json);
+
+  if (args.view === '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 });
+    }
+    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 runJsonCandidateChain(docxCandidates, [
+    'find-template-migration-targets',
+    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');
+  }
+  const catalogTargets = new Map(catalog.targets.map(item => [item.id, item]));
+  for (const target of targetPage.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`);
+    }
+  }
+  return migrationQueryResult({
+    runtime: commandRuntime(targetResult),
+    catalog,
+    view: args.view,
+    action,
+    source,
+    items: targetPage.targets,
+    offset: targetPage.offset,
+    total: targetPage.total,
+  });
+}
+
+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',
+    runtime,
+    sourceSha256: catalog.sourceSha256,
+    baselineSha256: catalog.baselineSha256,
+    view,
+    action,
+    source,
+    items,
+    page: {
+      offset,
+      returned: items.length,
+      total,
+      hasMore: offset + items.length < total,
+    },
+  };
+}
+
 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.4.0",
+  "version": "0.6.0",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",