@tiwater/office-mcp 0.2.0 → 0.4.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];
 
@@ -99,10 +100,42 @@ async function runCommand(candidate, args, options) {
     child.on('close', code => {
       const allowedExitCodes = options.allowedExitCodes ?? [0];
       if (allowedExitCodes.includes(code)) {
-        resolve({ code, stdout, stderr, command: candidate.command, args: commandArgs });
+        resolve({ code, stdout, stderr, command: candidate.command, args: commandArgs, cwd });
         return;
       }
       reject(new Error(`${candidate.command} ${commandArgs.join(' ')} failed with exit code ${code}\n${stderr || stdout}`));
     });
   });
 }
+
+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

@@ -15,7 +15,6 @@ Shared stdio MCP server for Office document workflows.
 - `xlsx_export_json`
 - `xlsx_validate`
 - `pptx_inspect`
-- `pptx_inspect_detail`
 - `pptx_export_json`
 
 ## Run
@@ -26,3 +25,8 @@ 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 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.

package/office/index.mjs

@@ -1,347 +1,312 @@
 #!/usr/bin/env node
+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 { McpStdioServer } from '../_shared/mcp-stdio.mjs';
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
 import {
   commandCandidate,
   createToolResult,
-  maybeReadJson,
   requireString,
-  resolveRepoPath,
-  runCandidateChain,
   runJsonCandidateChain,
   withTempJsonFile,
 } from '../_shared/tool-runtime.mjs';
 
+const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const invocationCwd = process.cwd();
+
 const docxCandidates = [
-  commandCandidate('tiwater-docx'),
+  commandCandidate('tiwater-docx', [], { cwd: invocationCwd }),
 ];
 
 const xlsxCandidates = [
-  commandCandidate('tiwater-xlsx'),
+  commandCandidate('tiwater-xlsx', [], { cwd: invocationCwd }),
 ];
 
 const pptxCandidates = [
-  commandCandidate('tiwater-pptx'),
+  commandCandidate('tiwater-pptx', [], { cwd: invocationCwd }),
 ];
 
-function templateMigrationInputSchema() {
-  return {
-    type: 'object',
-    properties: {
-      source: { type: 'string', description: 'Path to the current source DOCX.' },
-      baseline: { type: 'string', description: 'Path to the selected current baseline DOCX.' },
-      output: { type: 'string', description: 'Path to the migrated output DOCX.' },
-      choices: {
-        type: 'array',
-        description: 'Exactly one business choice for every source id returned by docx_list_migration_choices.',
-        items: {
-          type: 'object',
-          properties: {
-            sourceChoiceId: { type: 'string' },
-            action: {
-              type: 'string',
-              enum: ['place-content', 'keep-template-content', 'keep-template-label', 'select-template-option', 'exclude-source', 'review-source'],
-            },
-            targetChoiceId: { type: 'string', description: 'Required only when the selected action uses a baseline target.' },
-            cardinality: { type: 'string', enum: ['one', 'all'] },
-          },
-          required: ['sourceChoiceId', 'action'],
-          additionalProperties: false,
-        },
-      },
-      templateCleanup: {
-        type: 'array',
-        description: 'Optional baseline-owned placeholders or example rows to clear.',
-        items: {
-          type: 'object',
-          properties: {
-            targetChoiceId: { type: 'string' },
-            scope: { type: 'string', enum: ['cell', 'row'] },
-          },
-          required: ['targetChoiceId', 'scope'],
-          additionalProperties: false,
-        },
-      },
-    },
-    required: ['source', 'baseline', 'output', 'choices'],
-    additionalProperties: false,
-  };
+const pathInput = z.string().trim().min(1);
+const migrationAction = z.enum([
+  'place-content',
+  'keep-template-content',
+  'keep-template-label',
+  'select-template-option',
+  'exclude-source',
+  'review-source',
+]);
+const targetActions = new Set([
+  'place-content',
+  'keep-template-content',
+  'keep-template-label',
+  'select-template-option',
+]);
+const terminalActions = new Set(['exclude-source', 'review-source']);
+
+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` });
+  }
+  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({
+  targetChoiceId: z.string().trim().min(1),
+  scope: z.enum(['cell', 'row']),
+}).strict();
+
+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();
+
+const runtimeIdentity = z.object({
+  command: z.string(),
+  cwd: z.string(),
+}).strict();
+
+const migrationChoiceOutput = z.object({
+  id: z.string(),
+  kind: z.string(),
+  scope: z.string(),
+  text: z.string().nullable(),
+  count: z.number().int(),
+  requiredCardinality: z.string().nullable(),
+  context: z.record(z.string(), z.unknown()).nullable(),
+  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();
+
+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,
+  artifact,
+  summary: z.object({
+    schema: z.string(),
+    pass: z.boolean(),
+    sourceSha256: z.string(),
+    baselineSha256: z.string(),
+    sourceCount: z.number().int().nonnegative(),
+    targetCount: z.number().int().nonnegative(),
+  }).strict(),
+}).strict();
+
+function migrationReceiptOutput(tool) {
+  return z.object({
+    tool: z.literal(tool),
+    runtime: runtimeIdentity,
+    artifact,
+    summary: 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(),
+      failureCount: z.number().int().nonnegative(),
+    }).strict(),
+  }).strict();
 }
 
-const runtimeIdentitySchema = {
-  type: 'object',
-  properties: {
-    command: { type: 'string' },
-    cwd: { type: 'string' },
-  },
-  required: ['command', 'cwd'],
-  additionalProperties: false,
-};
-
-const migrationChoiceSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    kind: { type: 'string' },
-    scope: { type: 'string' },
-    text: { type: ['string', 'null'] },
-    count: { type: 'integer' },
-    requiredCardinality: { type: ['string', 'null'] },
-    context: { type: ['object', 'null'] },
-    allowedActions: { type: 'array', items: { type: 'string' } },
-  },
-  required: ['id', 'kind', 'scope', 'text', 'count', 'requiredCardinality', 'context', 'allowedActions'],
-  additionalProperties: false,
-};
-
-const migrationCatalogOutputSchema = {
-  type: 'object',
-  properties: {
-    tool: { const: 'docx_list_migration_choices' },
-    runtime: runtimeIdentitySchema,
-    catalog: {
-      type: 'object',
-      properties: {
-        schema: { type: 'string' },
-        pass: { type: 'boolean' },
-        sourceSha256: { type: 'string' },
-        baselineSha256: { type: 'string' },
-        sources: { type: 'array', items: migrationChoiceSchema },
-        targets: { type: 'array', items: migrationChoiceSchema },
-      },
-      required: ['schema', 'pass', 'sourceSha256', 'baselineSha256', 'sources', 'targets'],
-      additionalProperties: false,
-    },
-  },
-  required: ['tool', 'runtime', 'catalog'],
-  additionalProperties: false,
-};
-
-function migrationReceiptOutputSchema(tool) {
-  return {
-    type: 'object',
-    properties: {
-      tool: { const: tool },
-      runtime: runtimeIdentitySchema,
-      receipt: {
-        type: 'object',
-        properties: {
-          schema: { type: 'string' },
-          toolVersion: { type: 'string' },
-          status: { type: 'string', enum: ['pass', 'review-required', 'failed'] },
-          pass: { type: 'boolean' },
-          reviewRequired: { type: 'boolean' },
-          outputVerified: { type: 'boolean' },
-          output: { type: ['string', 'null'] },
-          plan: { type: ['string', 'null'] },
-          failures: { type: 'array', items: { type: 'object' } },
-        },
-        required: ['schema', 'toolVersion', 'status', 'pass', 'reviewRequired', 'outputVerified', 'output', 'plan', 'failures'],
-        additionalProperties: true,
-      },
-    },
-    required: ['tool', 'runtime', 'receipt'],
-    additionalProperties: false,
-  };
+function artifactOutput(tool) {
+  return z.object({ tool: z.literal(tool), runtime: runtimeIdentity, artifact }).strict();
 }
 
 const tools = [
   {
     name: 'docx_inspect',
-    description: 'Inspect a DOCX document and return a unified structural report including placeholders, comments, anchors, tables, fields, and formatting metrics.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string', description: 'Absolute or relative path to a .docx file.' } },
-      required: ['input'],
-    },
-  },
-  {
-    name: 'docx_inspect_tables',
-    description: 'Inspect DOCX body tables with row, cell, merge, paragraph alignment, run font, color, underline, and text-fill details.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string', description: 'Absolute or relative path to a .docx file.' } },
-      required: ['input'],
-    },
+    description: 'Inspect a DOCX document and write one unified JSON observation containing placeholders, comments, anchors, tables, fields, flow, fonts, and formatting metrics.',
+    inputSchema: artifactInput,
+    outputSchema: artifactOutput('docx_inspect'),
+    handler: docxInspect,
   },
   {
     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.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        source: { type: 'string', description: 'Path to the current source DOCX.' },
-        baseline: { type: 'string', description: 'Path to the selected current baseline DOCX.' },
-      },
-      required: ['source', 'baseline'],
-      additionalProperties: false,
-    },
-    outputSchema: migrationCatalogOutputSchema,
+    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,
+    handler: docxListMigrationChoices,
   },
   {
     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.',
-    inputSchema: templateMigrationInputSchema(),
-    outputSchema: migrationReceiptOutputSchema('docx_migrate_template'),
+    inputSchema: templateMigrationInput,
+    outputSchema: migrationReceiptOutput('docx_migrate_template'),
+    handler: docxMigrateTemplate,
   },
   {
     name: 'docx_verify_migration',
     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: templateMigrationInputSchema(),
-    outputSchema: migrationReceiptOutputSchema('docx_verify_migration'),
+    inputSchema: templateMigrationInput,
+    outputSchema: migrationReceiptOutput('docx_verify_migration'),
+    handler: docxVerifyMigration,
   },
   {
     name: 'docx_compare',
     description: 'Compare two DOCX files and report package, metric, and style differences.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        baseline: { type: 'string' },
-        updated: { type: 'string' },
-      },
-      required: ['baseline', 'updated'],
-    },
+    inputSchema: z.object({ baseline: pathInput, updated: pathInput }).strict(),
+    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: {
-      type: 'object',
-      properties: {
-        sourceTemplate: { type: 'string' },
-        targetTemplate: { type: 'string' },
-      },
-      required: ['sourceTemplate', 'targetTemplate'],
-    },
+    inputSchema: z.object({ sourceTemplate: pathInput, targetTemplate: pathInput }).strict(),
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    handler: docxValidateTemplateTransform,
   },
   {
     name: 'docx_export_json',
-    description: 'Export the body content of a DOCX document as structured JSON.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        input: { type: 'string' },
-        output: { type: 'string' },
-      },
-      required: ['input'],
-    },
+    description: 'Export DOCX body content to a new JSON artifact without returning the full document through MCP.',
+    inputSchema: artifactInput,
+    outputSchema: artifactOutput('docx_export_json'),
+    handler: docxExportJson,
   },
   {
     name: 'xlsx_inspect',
-    description: 'Inspect an XLSX workbook and return sheet-level metrics, used ranges, formula counts, and merged ranges.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string' } },
-      required: ['input'],
-    },
+    description: 'Inspect an XLSX workbook and write one JSON observation containing workbook structure, exported values, formulas, styles, merged ranges, and conversion evidence.',
+    inputSchema: artifactInput,
+    outputSchema: artifactOutput('xlsx_inspect'),
+    handler: xlsxInspect,
   },
   {
     name: 'xlsx_export_json',
     description: 'Export workbook sheet data from XLSX as structured JSON.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        input: { type: 'string' },
-        output: { type: 'string' },
-        resolveMergedCells: { type: 'boolean', description: 'Resolve merged cells to project values' }
-      },
-      required: ['input'],
-    },
+    inputSchema: z.object({
+      input: pathInput,
+      output: pathInput.describe('New JSON artifact path. Existing files are never overwritten.'),
+      resolveMergedCells: z.boolean().optional().describe('Resolve merged cells to project values.'),
+    }).strict(),
+    outputSchema: artifactOutput('xlsx_export_json'),
+    handler: xlsxExportJson,
   },
   {
     name: 'xlsx_validate',
     description: 'Validate an XLSX workbook package and return Open XML validation evidence.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string', description: 'Absolute or relative path to a .xlsx file.' } },
-      required: ['input'],
-    },
+    inputSchema: inputOnly,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    handler: xlsxValidate,
   },
   {
     name: 'pptx_inspect',
-    description: 'Inspect a PPTX file and return slide metrics and discovered placeholders.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string' } },
-      required: ['input'],
-    },
-  },
-  {
-    name: 'pptx_inspect_detail',
-    description: 'Inspect a PPTX file and return detailed slide, shape, transform, paragraph, and run-format evidence.',
-    inputSchema: {
-      type: 'object',
-      properties: { input: { type: 'string' } },
-      required: ['input'],
-    },
+    description: 'Inspect a PPTX file and write one detailed JSON observation containing slides, masters, layouts, shapes, transforms, paragraphs, runs, and placeholders.',
+    inputSchema: artifactInput,
+    outputSchema: artifactOutput('pptx_inspect'),
+    handler: pptxInspect,
   },
   {
     name: 'pptx_export_json',
-    description: 'Export PPTX slide text and placeholder hints as structured JSON.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        input: { type: 'string' },
-        output: { type: 'string' },
-      },
-      required: ['input'],
-    },
+    description: 'Export PPTX slide text, notes, and placeholder hints to a new JSON artifact without returning the full presentation through MCP.',
+    inputSchema: artifactInput,
+    outputSchema: artifactOutput('pptx_export_json'),
+    handler: pptxExportJson,
   },
 ];
 
-async function callTool(name, args) {
-  switch (name) {
-    case 'docx_inspect':
-      return createToolResult(await docxInspect(args));
-    case 'docx_inspect_tables':
-      return createToolResult(await docxInspectTables(args));
-    case 'docx_list_migration_choices':
-      return createToolResult(await docxListMigrationChoices(args));
-    case 'docx_migrate_template':
-      return createToolResult(await docxMigrateTemplate(args));
-    case 'docx_verify_migration':
-      return createToolResult(await docxVerifyMigration(args));
-    case 'docx_compare':
-      return createToolResult(await docxCompare(args));
-    case 'docx_validate_template_transform':
-      return createToolResult(await docxValidateTemplateTransform(args));
-    case 'docx_export_json':
-      return createToolResult(await docxExportJson(args));
-    case 'xlsx_inspect':
-      return createToolResult(await xlsxInspect(args));
-    case 'xlsx_export_json':
-      return createToolResult(await xlsxExportJson(args));
-    case 'xlsx_validate':
-      return createToolResult(await xlsxValidate(args));
-    case 'pptx_inspect':
-      return createToolResult(await pptxInspect(args));
-    case 'pptx_inspect_detail':
-      return createToolResult(await pptxInspectDetail(args));
-    case 'pptx_export_json':
-      return createToolResult(await pptxExportJson(args));
-    default:
-      throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32601 });
+function buildServer() {
+  const server = new McpServer(
+    { name: 'tiwater-office', version: packageMetadata.version },
+    {
+      instructions: 'Use the Office tools for technical document observation. For template migration, list the current choices, select only allowed business actions, migrate once, and independently verify the result. Never invent document values, identities, coordinates, plans, or edit operations.',
+    },
+  );
+  for (const tool of tools) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+      },
+      async args => createToolResult(await tool.handler(args)),
+    );
   }
+  return server;
 }
 
 async function docxInspect(args) {
   const input = requireString(args.input, 'input');
   const result = await runJsonCandidateChain(docxCandidates, ['inspect', input, '--json']);
-  return { tool: 'docx_inspect', runtime: commandRuntime(result), report: result.json };
-}
-
-async function docxInspectTables(args) {
-  const input = requireString(args.input, 'input');
-  const result = await runJsonCandidateChain(docxCandidates, ['inspect-tables', input, '--json']);
-  return { tool: 'docx_inspect_tables', runtime: commandRuntime(result), report: result.json };
+  return {
+    tool: 'docx_inspect',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
 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 docxMigrateTemplate(args) {
@@ -369,7 +334,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,
+      },
+    };
   });
 }
 
@@ -389,19 +370,22 @@ async function docxValidateTemplateTransform(args) {
 
 async function docxExportJson(args) {
   const input = requireString(args.input, 'input');
-  if (args.output) {
-    const output = requireString(args.output, 'output');
-    const result = await runCandidateChain(docxCandidates, ['export-json', input, output]);
-    return { tool: 'docx_export_json', runtime: commandRuntime(result), outputPath: output, document: await maybeReadJson(output) };
-  }
-  const result = await runCandidateChain(docxCandidates, ['export-json', input]);
-  return { tool: 'docx_export_json', runtime: commandRuntime(result), document: JSON.parse(result.stdout) };
+  const result = await runJsonCandidateChain(docxCandidates, ['export-json', input]);
+  return {
+    tool: 'docx_export_json',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
 async function xlsxInspect(args) {
   const input = requireString(args.input, 'input');
   const result = await runJsonCandidateChain(xlsxCandidates, ['inspect', input, '--json']);
-  return { tool: 'xlsx_inspect', runtime: commandRuntime(result), report: result.json };
+  return {
+    tool: 'xlsx_inspect',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
 async function xlsxExportJson(args) {
@@ -410,14 +394,12 @@ async function xlsxExportJson(args) {
   if (args.resolveMergedCells) {
     cmdArgs.push('--resolve-merged-cells');
   }
-  if (args.output) {
-    const output = requireString(args.output, 'output');
-    cmdArgs.push(output);
-    const result = await runCandidateChain(xlsxCandidates, cmdArgs);
-    return { tool: 'xlsx_export_json', runtime: commandRuntime(result), outputPath: output, workbook: await maybeReadJson(output) };
-  }
-  const result = await runCandidateChain(xlsxCandidates, cmdArgs);
-  return { tool: 'xlsx_export_json', runtime: commandRuntime(result), workbook: JSON.parse(result.stdout) };
+  const result = await runJsonCandidateChain(xlsxCandidates, cmdArgs);
+  return {
+    tool: 'xlsx_export_json',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
 async function xlsxValidate(args) {
@@ -429,24 +411,33 @@ async function xlsxValidate(args) {
 async function pptxInspect(args) {
   const input = requireString(args.input, 'input');
   const result = await runJsonCandidateChain(pptxCandidates, ['inspect', input, '--json']);
-  return { tool: 'pptx_inspect', runtime: commandRuntime(result), report: result.json };
+  return {
+    tool: 'pptx_inspect',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
-async function pptxInspectDetail(args) {
+async function pptxExportJson(args) {
   const input = requireString(args.input, 'input');
-  const result = await runJsonCandidateChain(pptxCandidates, ['inspect', input, '--json', '--detail']);
-  return { tool: 'pptx_inspect_detail', runtime: commandRuntime(result), report: result.json };
+  const result = await runJsonCandidateChain(pptxCandidates, ['export-json', input]);
+  return {
+    tool: 'pptx_export_json',
+    runtime: commandRuntime(result),
+    artifact: await writeJsonArtifact(requireString(args.output, 'output'), result.json),
+  };
 }
 
-async function pptxExportJson(args) {
-  const input = requireString(args.input, 'input');
-  if (args.output) {
-    const output = requireString(args.output, 'output');
-    const result = await runCandidateChain(pptxCandidates, ['export-json', input, output]);
-    return { tool: 'pptx_export_json', runtime: commandRuntime(result), outputPath: output, document: await maybeReadJson(output) };
-  }
-  const result = await runCandidateChain(pptxCandidates, ['export-json', input]);
-  return { tool: 'pptx_export_json', runtime: commandRuntime(result), document: JSON.parse(result.stdout) };
+async function writeJsonArtifact(output, payload) {
+  const fullPath = path.resolve(output);
+  await mkdir(path.dirname(fullPath), { recursive: true });
+  const bytes = Buffer.from(`${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  await writeFile(fullPath, bytes, { flag: 'wx' });
+  return {
+    path: fullPath,
+    sha256: createHash('sha256').update(bytes).digest('hex'),
+    bytes: bytes.length,
+  };
 }
 
 function commandRuntime(result) {
@@ -456,7 +447,7 @@ function commandRuntime(result) {
   };
 }
 
-await new McpStdioServer({ name: 'tiwater-office', version: '0.2.0', tools, callTool }).start();
+serveStdio(buildServer);
 
 async function runXlsxValidateCandidateChain(args) {
   const errors = [];
@@ -487,7 +478,7 @@ async function runXlsxValidateCandidateChain(args) {
 
 async function runValidationCommand(candidate, args) {
   const env = { ...process.env, ...(candidate.env || {}) };
-  const cwd = candidate.cwd || resolveRepoPath();
+  const cwd = candidate.cwd || process.cwd();
   const commandArgs = [...(candidate.argsPrefix || []), ...args];
 
   return await new Promise((resolve, reject) => {
@@ -506,7 +497,7 @@ async function runValidationCommand(candidate, args) {
     child.on('error', reject);
     child.on('close', code => {
       if (code === 0 || code === 1) {
-        resolve({ code, stdout, stderr, command: candidate.command, args: commandArgs });
+        resolve({ code, stdout, stderr, command: candidate.command, args: commandArgs, cwd });
         return;
       }
       reject(new Error(`${candidate.command} ${commandArgs.join(' ')} failed with exit code ${code}\n${stderr || stdout}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Published MCP server for Tiwater Office document capabilities",
   "type": "module",
   "license": "MIT",
@@ -12,8 +12,11 @@
   "bin": {
     "tiwater-office-mcp": "office/index.mjs"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "files": [
-    "_shared/*.mjs",
+    "_shared/tool-runtime.mjs",
     "office/index.mjs",
     "office/README.md"
   ],
@@ -22,5 +25,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.4.3"
   }
 }

package/_shared/mcp-stdio.mjs

@@ -1,152 +0,0 @@
-import process from 'node:process';
-
-const JSONRPC_VERSION = '2.0';
-const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];
-const FALLBACK_PROTOCOL_VERSION = '2025-06-18';
-
-function writeMessage(message) {
-  process.stdout.write(`${JSON.stringify(message)}\n`);
-}
-
-function toError(code, message, data) {
-  return { code, message, ...(data === undefined ? {} : { data }) };
-}
-
-function normalizeToolCallError(error) {
-  if (!error) return toError(-32603, 'Unknown error');
-  if (error.code && error.message) return error;
-  return toError(-32603, error instanceof Error ? error.message : String(error));
-}
-
-export class McpStdioServer {
-  constructor({ name, version, instructions, tools, callTool, logger = console.error }) {
-    this.serverInfo = { name, version };
-    this.instructions = instructions;
-    this.tools = tools;
-    this.callTool = callTool;
-    this.logger = logger;
-    this.lineBuffer = '';
-    this.binaryBuffer = Buffer.alloc(0);
-    this.initialized = false;
-  }
-
-  start() {
-    process.stdin.on('data', chunk => this.#onData(chunk));
-    process.stdin.on('end', () => process.exit(0));
-  }
-
-  #onData(chunk) {
-    const text = chunk.toString('utf8');
-
-    if (this.binaryBuffer.length > 0 || text.includes('Content-Length:')) {
-      this.binaryBuffer = Buffer.concat([this.binaryBuffer, chunk]);
-      this.#drainContentLengthBuffer();
-      return;
-    }
-
-    this.lineBuffer += text;
-    while (true) {
-      const newlineIndex = this.lineBuffer.indexOf('\n');
-      if (newlineIndex === -1) return;
-      const line = this.lineBuffer.slice(0, newlineIndex).replace(/\r$/, '').trim();
-      this.lineBuffer = this.lineBuffer.slice(newlineIndex + 1);
-      if (!line) continue;
-      this.#parseAndHandle(line, null);
-    }
-  }
-
-  #drainContentLengthBuffer() {
-    while (true) {
-      const headerEnd = this.binaryBuffer.indexOf('\r\n\r\n');
-      if (headerEnd === -1) return;
-
-      const headerText = this.binaryBuffer.subarray(0, headerEnd).toString('utf8');
-      const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
-      if (!lengthMatch) {
-        this.logger('Missing Content-Length header');
-        this.binaryBuffer = Buffer.alloc(0);
-        return;
-      }
-
-      const contentLength = Number(lengthMatch[1]);
-      const messageStart = headerEnd + 4;
-      const messageEnd = messageStart + contentLength;
-      if (this.binaryBuffer.length < messageEnd) return;
-
-      const body = this.binaryBuffer.subarray(messageStart, messageEnd).toString('utf8');
-      this.binaryBuffer = this.binaryBuffer.subarray(messageEnd);
-      this.#parseAndHandle(body, null);
-    }
-  }
-
-  #parseAndHandle(body, idHint) {
-    let message;
-    try {
-      message = JSON.parse(body);
-    } catch (error) {
-      writeMessage({ jsonrpc: JSONRPC_VERSION, id: idHint, error: toError(-32700, 'Parse error', String(error)) });
-      return;
-    }
-
-    void this.#handleMessage(message);
-  }
-
-  async #handleMessage(message) {
-    if (!message || message.jsonrpc !== JSONRPC_VERSION || typeof message.method !== 'string') {
-      if ('id' in (message || {})) {
-        writeMessage({ jsonrpc: JSONRPC_VERSION, id: message.id ?? null, error: toError(-32600, 'Invalid Request') });
-      }
-      return;
-    }
-
-    const { id, method, params = {} } = message;
-    const isNotification = id === undefined;
-
-    try {
-      switch (method) {
-        case 'initialize': {
-          const requested = params.protocolVersion;
-          const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : FALLBACK_PROTOCOL_VERSION;
-          const result = {
-            protocolVersion,
-            capabilities: { tools: {} },
-            serverInfo: this.serverInfo,
-            ...(this.instructions ? { instructions: this.instructions } : {}),
-          };
-          if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, result });
-          return;
-        }
-        case 'notifications/initialized': {
-          this.initialized = true;
-          return;
-        }
-        case 'ping': {
-          if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, result: {} });
-          return;
-        }
-        case 'tools/list': {
-          if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, result: { tools: this.tools } });
-          return;
-        }
-        case 'tools/call': {
-          const name = params?.name;
-          const args = params?.arguments ?? {};
-          if (typeof name !== 'string' || !name) {
-            if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, error: toError(-32602, 'Invalid params: missing tool name') });
-            return;
-          }
-          const result = await this.callTool(name, args);
-          if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, result });
-          return;
-        }
-        default: {
-          if (!isNotification) writeMessage({ jsonrpc: JSONRPC_VERSION, id, error: toError(-32601, `Method not found: ${method}`) });
-        }
-      }
-    } catch (error) {
-      if (!isNotification) {
-        writeMessage({ jsonrpc: JSONRPC_VERSION, id, error: normalizeToolCallError(error) });
-      }
-    }
-  }
-}