@tiwater/office-mcp 0.3.0 → 0.5.0

package/_shared/tool-runtime.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -78,7 +79,7 @@ export function requireString(value, label) {
 }
 
 async function runCommand(candidate, args, options) {
-  const env = { ...process.env, ...(candidate.env || {}), ...(options.env || {}) };
+  const env = await withDotnetRoot({ ...process.env, ...(candidate.env || {}), ...(options.env || {}) });
   const cwd = candidate.cwd || options.cwd || repoRoot;
   const commandArgs = [...(candidate.argsPrefix || []), ...args];
 
@@ -106,3 +107,35 @@ async function runCommand(candidate, args, options) {
     });
   });
 }
+
+async function withDotnetRoot(env) {
+  const architectureVariable = process.arch === 'arm64'
+    ? 'DOTNET_ROOT_ARM64'
+    : process.arch === 'x64'
+      ? 'DOTNET_ROOT_X64'
+      : null;
+  if (env.DOTNET_ROOT || (architectureVariable && env[architectureVariable])) return env;
+
+  const dotnet = await findOnPath(process.platform === 'win32' ? 'dotnet.exe' : 'dotnet', env.PATH);
+  if (!dotnet) return env;
+
+  const root = path.dirname(dotnet);
+  return {
+    ...env,
+    DOTNET_ROOT: root,
+    ...(architectureVariable ? { [architectureVariable]: root } : {}),
+  };
+}
+
+async function findOnPath(command, pathValue) {
+  for (const directory of String(pathValue ?? '').split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(directory, command);
+    try {
+      await fs.access(candidate, fsConstants.X_OK);
+      return candidate;
+    } catch {
+      // Continue to the next PATH entry.
+    }
+  }
+  return null;
+}

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`

package/office/index.mjs

@@ -72,6 +72,7 @@ const templateMigrationInput = z.object({
   source: pathInput.describe('Path to the current source DOCX.'),
   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.'),
   templateCleanup: z.array(templateCleanupInput).optional().describe('Optional baseline-owned placeholders or example rows to clear.'),
 }).strict();
@@ -92,24 +93,103 @@ const migrationChoiceOutput = z.object({
   allowedActions: z.array(z.string()),
 }).strict();
 
+const migrationCatalog = z.object({
+  schema: z.string(),
+  pass: z.boolean(),
+  sourceSha256: z.string(),
+  baselineSha256: z.string(),
+  sources: z.array(migrationChoiceOutput),
+  targets: z.array(migrationChoiceOutput),
+}).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(),
+  toolVersion: z.string(),
+  status: z.enum(['pass', 'review-required', 'failed']),
+  pass: z.boolean(),
+  reviewRequired: z.boolean(),
+  outputVerified: z.boolean(),
+  output: z.string().nullable(),
+  plan: z.string().nullable(),
+  failures: z.array(z.unknown()),
+}).passthrough();
+
+const inputOnly = z.object({ input: pathInput }).strict();
+const artifactInput = z.object({
+  input: pathInput,
+  output: pathInput.describe('New JSON artifact path. Existing files are never overwritten.'),
+}).strict();
+const artifact = z.object({
+  path: z.string(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  bytes: z.number().int().nonnegative(),
+}).strict();
+
 const migrationCatalogOutput = z.object({
   tool: z.literal('docx_list_migration_choices'),
   runtime: runtimeIdentity,
-  catalog: z.object({
+  artifact,
+  summary: z.object({
     schema: z.string(),
     pass: z.boolean(),
     sourceSha256: z.string(),
     baselineSha256: z.string(),
-    sources: z.array(migrationChoiceOutput),
-    targets: z.array(migrationChoiceOutput),
+    sourceCount: z.number().int().nonnegative(),
+    targetCount: z.number().int().nonnegative(),
   }).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 migrationChoiceQueryInput = z.discriminatedUnion('view', [
+  z.object({
+    catalog: pathInput.describe('Path returned by docx_list_migration_choices.'),
+    view: z.literal('sources'),
+    offset: z.number().int().nonnegative().optional(),
+    limit: z.number().int().min(1).max(10).optional(),
+  }).strict(),
+  z.object({
+    catalog: pathInput.describe('Path returned by docx_list_migration_choices.'),
+    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(),
+  }).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']),
+  source: migrationChoiceOutput.nullable(),
+  items: z.array(migrationChoiceOutput),
+  page: migrationQueryPage,
+}).strict();
+
 function migrationReceiptOutput(tool) {
   return z.object({
     tool: z.literal(tool),
     runtime: runtimeIdentity,
-    receipt: z.object({
+    artifact,
+    summary: z.object({
       schema: z.string(),
       toolVersion: z.string(),
       status: z.enum(['pass', 'review-required', 'failed']),
@@ -118,22 +198,11 @@ function migrationReceiptOutput(tool) {
       outputVerified: z.boolean(),
       output: z.string().nullable(),
       plan: z.string().nullable(),
-      failures: z.array(z.unknown()),
-    }).passthrough(),
+      failureCount: z.number().int().nonnegative(),
+    }).strict(),
   }).strict();
 }
 
-const inputOnly = z.object({ input: pathInput }).strict();
-const artifactInput = z.object({
-  input: pathInput,
-  output: pathInput.describe('New JSON artifact path. Existing files are never overwritten.'),
-}).strict();
-const artifact = z.object({
-  path: z.string(),
-  sha256: z.string().regex(/^[0-9a-f]{64}$/),
-  bytes: z.number().int().nonnegative(),
-}).strict();
-
 function artifactOutput(tool) {
   return z.object({ tool: z.literal(tool), runtime: runtimeIdentity, artifact }).strict();
 }
@@ -148,15 +217,23 @@ const tools = [
   },
   {
     name: 'docx_list_migration_choices',
-    description: 'List every current source item that still needs a business choice and the selectable current baseline targets. Returns opaque ids and context; 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 a run-local JSON artifact. Returns only artifact metadata and counts; it does not recommend a choice.',
     inputSchema: z.object({
       source: pathInput.describe('Path to the current source DOCX.'),
       baseline: pathInput.describe('Path to the selected current baseline DOCX.'),
+      output: pathInput.describe('New JSON artifact path. Existing files are never overwritten.'),
     }).strict(),
     outputSchema: migrationCatalogOutput,
-    annotations: { readOnlyHint: true, idempotentHint: true },
     handler: docxListMigrationChoices,
   },
+  {
+    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.',
+    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.',
@@ -169,7 +246,6 @@ const tools = [
     description: 'Independently re-resolve the same business choices and verify a migrated DOCX against the current source and baseline. This does not trust the migration receipt.',
     inputSchema: templateMigrationInput,
     outputSchema: migrationReceiptOutput('docx_verify_migration'),
-    annotations: { readOnlyHint: true, idempotentHint: true },
     handler: docxVerifyMigration,
   },
   {
@@ -270,7 +346,76 @@ async function docxListMigrationChoices(args) {
   const source = requireString(args.source, 'source');
   const baseline = requireString(args.baseline, 'baseline');
   const result = await runJsonCandidateChain(docxCandidates, ['list-template-migration-choices', source, baseline]);
-  return { tool: 'docx_list_migration_choices', runtime: commandRuntime(result), catalog: result.json };
+  const catalog = migrationCatalog.parse(result.json);
+  return {
+    tool: 'docx_list_migration_choices',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), catalog),
+    summary: {
+      schema: catalog.schema,
+      pass: catalog.pass,
+      sourceSha256: catalog.sourceSha256,
+      baselineSha256: catalog.baselineSha256,
+      sourceCount: catalog.sources.length,
+      targetCount: catalog.targets.length,
+    },
+  };
+}
+
+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 offset = args.offset ?? 0;
+  const limit = args.limit ?? 10;
+  let source = null;
+  let matches;
+
+  if (args.view === 'sources') {
+    matches = catalog.sources;
+  } 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)));
+  }
+
+  const items = matches.slice(offset, offset + limit);
+  return {
+    tool: 'docx_query_migration_choices',
+    catalogSha256: createHash('sha256').update(bytes).digest('hex'),
+    view: args.view,
+    source,
+    items,
+    page: {
+      offset,
+      returned: items.length,
+      total: matches.length,
+      hasMore: offset + items.length < matches.length,
+    },
+  };
+}
+
+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) {
@@ -298,7 +443,23 @@ async function runTemplateMigrationCommand(tool, command, args) {
       docxCandidates,
       [command, source, baseline, choicesPath, output],
       { allowedExitCodes: [0, 1] });
-    return { tool, runtime: commandRuntime(result), receipt: result.json };
+    const receipt = migrationReceipt.parse(result.json);
+    return {
+      tool,
+      runtime: commandRuntime(result),
+      artifact: await writeJsonArtifact(requireString(args.receiptOutput, 'receiptOutput'), receipt),
+      summary: {
+        schema: receipt.schema,
+        toolVersion: receipt.toolVersion,
+        status: receipt.status,
+        pass: receipt.pass,
+        reviewRequired: receipt.reviewRequired,
+        outputVerified: receipt.outputVerified,
+        output: receipt.output,
+        plan: receipt.plan,
+        failureCount: receipt.failures.length,
+      },
+    };
   });
 }
 

package/package.json

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