@tiwater/office-mcp 0.21.38 → 0.21.39

package/_shared/effect-kind.mjs

@@ -5,6 +5,7 @@ export const effectKindSchema = 'tiwater.provider-effect-kind/v1';
 export const documentRevisionRoleKey = 'x-tiwater-document-revision-role';
 
 const effectKinds = new Set([
+  'document-create',
   'document-mutation',
   'source-conversion',
   'native-render',
@@ -46,10 +47,15 @@ export function assertEffectKindToolContract(tool, expectedKind = undefined) {
   if (expectedKind !== undefined && metadata.kind !== expectedKind) {
     throw new Error(`effect-kind-mismatch:${tool?.name || 'unnamed'}:${metadata.kind}`);
   }
-  if (!bindings.some(binding => binding.role === 'read')) {
+  if (metadata.kind !== 'document-create' && !bindings.some(binding => binding.role === 'read')) {
     throw new Error(`effect-kind-source-binding-missing:${tool?.name || 'unnamed'}`);
   }
-  if (metadata.kind === 'document-mutation') {
+  if (metadata.kind === 'document-create') {
+    if (bindings.some(binding => binding.role === 'read')
+        || currentDocumentBindings.length !== 0 || effectiveWrites.length !== 1) {
+      throw new Error(`document-create-bindings-invalid:${tool?.name || 'unnamed'}`);
+    }
+  } else if (metadata.kind === 'document-mutation') {
     if (currentDocumentBindings.length !== 1) {
       throw new Error(`document-mutation-current-binding-invalid:${tool?.name || 'unnamed'}`);
     }
@@ -70,6 +76,16 @@ export function assertEffectKindToolContract(tool, expectedKind = undefined) {
   return metadata.kind;
 }
 
+export function documentCreateFileArguments(tool, args) {
+  assertEffectKindToolContract(tool, 'document-create');
+  const bindings = boundFileArguments(tool?.inputSchema, args);
+  const effectiveOutput = bindings.filter(binding => binding.role === 'write' && binding.effect);
+  if (bindings.some(binding => binding.role === 'read') || effectiveOutput.length !== 1) {
+    throw new Error(`document-create-file-arguments-invalid:${tool?.name || 'unnamed'}`);
+  }
+  return { effectiveOutput: effectiveOutput[0].value };
+}
+
 export function documentMutationFileArguments(tool, args) {
   assertEffectKindToolContract(tool, 'document-mutation');
   const bindings = boundFileArguments(tool?.inputSchema, args);

package/office/contracts/docx_create.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/docx_create/v1",
+  "type": "object",
+  "properties": {
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "New DOCX path. Existing files are never overwritten.",
+      "x-tiwater-file-role": "write"
+    },
+    "receiptOutput": {
+      "type": "string",
+      "minLength": 1,
+      "description": "New JSON receipt path. Existing files are never overwritten.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["output", "receiptOutput"],
+  "additionalProperties": false
+}

package/office/contracts/pptx_read_shape.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/pptx_read_shape/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Current PPTX presentation.",
+      "x-tiwater-file-role": "read"
+    },
+    "slideNumber": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "Exact one-based slide number returned by presentation observation."
+    },
+    "shapeId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 4294967295,
+      "description": "Exact native shape id returned by pptx_read_slide."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based text-segment offset within the selected shape. Continue only when another segment is needed."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 4,
+      "description": "Maximum text segments in this bounded page."
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return this selected technical page directly when it fits the response limit. May be combined with output."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional immutable JSON artifact path for this selected technical page. May be combined with returnContent.",
+      "x-tiwater-file-role": "write"
+    }
+  },
+  "required": ["input", "slideNumber", "shapeId", "limit", "returnContent"],
+  "additionalProperties": false
+}

package/office/contracts/pptx_read_slide.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/pptx_read_slide/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Current PPTX presentation.",
+      "x-tiwater-file-role": "read"
+    },
+    "slideNumber": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "Exact one-based slide number returned by presentation observation."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based shape offset in native z-order on the selected slide. Continue only when another selected shape is needed."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 8,
+      "description": "Maximum shapes in this bounded page."
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return this selected technical page directly when it fits the response limit. May be combined with output."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional immutable JSON artifact path for this selected technical page. May be combined with returnContent.",
+      "x-tiwater-file-role": "write"
+    }
+  },
+  "required": ["input", "slideNumber", "limit", "returnContent"],
+  "additionalProperties": false
+}

package/office/contracts/tiwater-office-provider-contract-manifest-v1.json

@@ -2,7 +2,7 @@
   "schema": "tiwater.office-provider-contract-manifest/v1",
   "provider": {
     "id": "@tiwater/office-mcp",
-    "version": "0.21.38"
+    "version": "0.21.39"
   },
   "tools": [
     {
@@ -38,6 +38,17 @@
         "sha256": "a6d59ee785d8ab3994eb6f539b48411b272565ac136219de58d39a449b3112f3"
       }
     },
+    {
+      "name": "docx_create",
+      "providerContract": {
+        "source": "packages/docx-cli/contracts/mcp-input/docx_create.schema.json",
+        "sha256": "1cf22a23fc5d8b27fff6f50db2672be623696eac79ea986053e703274eab5e3e"
+      },
+      "inputContract": {
+        "path": "office/contracts/docx_create.schema.json",
+        "sha256": "1cf22a23fc5d8b27fff6f50db2672be623696eac79ea986053e703274eab5e3e"
+      }
+    },
     {
       "name": "docx_delete_object",
       "providerContract": {
@@ -335,6 +346,28 @@
         "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       }
     },
+    {
+      "name": "pptx_read_shape",
+      "providerContract": {
+        "source": "packages/pptx-cli/contracts/mcp-input/pptx_read_shape.schema.json",
+        "sha256": "63bf1819f95514dad3d6f43a58795aa8b57bf9d1f7075edcfb11ddd3253b83e4"
+      },
+      "inputContract": {
+        "path": "office/contracts/pptx_read_shape.schema.json",
+        "sha256": "63bf1819f95514dad3d6f43a58795aa8b57bf9d1f7075edcfb11ddd3253b83e4"
+      }
+    },
+    {
+      "name": "pptx_read_slide",
+      "providerContract": {
+        "source": "packages/pptx-cli/contracts/mcp-input/pptx_read_slide.schema.json",
+        "sha256": "3a2aaca3fd11da490863e1a2d60bf2f120e4e24991b457e316de04b5c9cc889a"
+      },
+      "inputContract": {
+        "path": "office/contracts/pptx_read_slide.schema.json",
+        "sha256": "3a2aaca3fd11da490863e1a2d60bf2f120e4e24991b457e316de04b5c9cc889a"
+      }
+    },
     {
       "name": "pptx_replace_picture_image",
       "providerContract": {

package/office/index.mjs

@@ -25,6 +25,7 @@ import {
 import { withOutputWriteLock } from '../_shared/output-write-lock.mjs';
 import { evidenceRoleMetadata } from '../_shared/evidence-role.mjs';
 import {
+  documentCreateFileArguments,
   documentMutationFileArguments,
   effectKindMetadata,
 } from '../_shared/effect-kind.mjs';
@@ -178,6 +179,13 @@ function fixedEditOutput(tool) {
   }).strict();
 }
 
+function fixedCreateOutput(tool) {
+  return z.object({
+    tool: z.literal(tool), runtime: runtimeIdentity, receipt: artifact, output: artifact,
+    summary: z.object({ pass: z.literal(true), operationCount: z.literal(1), appliedCount: z.literal(1) }).strict(),
+  }).strict();
+}
+
 function largeResultOutput(tool) {
   return z.object({
     tool: z.literal(tool),
@@ -288,6 +296,102 @@ const pptxInspectionSummary = z.object({
   }).strict()).max(6),
 }).strict();
 
+const pptxSlidePageSummary = z.object({
+  schema: z.literal('tiwater.pptx-slide-page-receipt/v1'),
+  slideNumber: z.number().int().positive(),
+  slidePath: z.string().min(1),
+  masterPath: z.string().min(1).nullable(),
+  layoutPath: z.string().min(1).nullable(),
+  totalShapeCount: z.number().int().nonnegative(),
+  returnedShapeCount: z.number().int().nonnegative(),
+  remaining: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative().nullable(),
+}).strict();
+
+const pptxShapeTextPageSummary = z.object({
+  schema: z.literal('tiwater.pptx-shape-text-page-receipt/v1'),
+  slideNumber: z.number().int().positive(),
+  shapeId: z.number().int().positive(),
+  totalSegmentCount: z.number().int().nonnegative(),
+  returnedSegmentCount: z.number().int().nonnegative(),
+  remaining: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative().nullable(),
+}).strict();
+
+const pptxTransform = z.object({
+  x: z.number().int(),
+  y: z.number().int(),
+  cx: z.number().int(),
+  cy: z.number().int(),
+}).strict();
+
+const pptxSlideShapeIdentity = z.object({
+  shapeId: z.number().int().positive(),
+  name: z.string().max(120),
+  kind: z.string().min(1).max(40),
+  zOrder: z.number().int().nonnegative(),
+  placeholderType: z.string().max(120).nullable(),
+  placeholderPresent: z.boolean(),
+  placeholderIndex: z.number().int().nonnegative().nullable(),
+  mediaPartPath: z.string().max(240).nullable(),
+  mediaSha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+  textPreview: z.string().max(240),
+  textLength: z.number().int().nonnegative(),
+  transform: pptxTransform.nullable(),
+  paragraphCount: z.number().int().nonnegative(),
+  runCount: z.number().int().nonnegative(),
+  hasTable: z.boolean(),
+}).strict();
+
+const pptxSlidePage = z.object({
+  schema: z.literal('tiwater.pptx-slide-page/v1'),
+  file: z.string(),
+  inputSha256: z.string().regex(/^[a-f0-9]{64}$/),
+  slideCount: z.number().int().nonnegative(),
+  slideSize: z.object({ cx: z.number().int().nonnegative(), cy: z.number().int().nonnegative() }).strict(),
+  slide: z.object({
+    slideNumber: z.number().int().positive(),
+    path: z.string().min(1),
+    masterPath: z.string().min(1).nullable(),
+    layoutPath: z.string().min(1).nullable(),
+    shapes: z.array(pptxSlideShapeIdentity).max(8),
+  }).strict(),
+  receipt: pptxSlidePageSummary,
+}).strict();
+
+const boundedPptxString = z.string().max(120).nullable();
+const pptxShapeTextSegment = z.object({
+  segmentIndex: z.number().int().nonnegative(),
+  runIndex: z.number().int().nonnegative(),
+  paragraphIndex: z.number().int().nonnegative(),
+  text: z.string().max(160),
+  textOffset: z.number().int().nonnegative(),
+  runTextLength: z.number().int().nonnegative(),
+  textContinues: z.boolean(),
+  paragraphAlignment: boundedPptxString,
+  fontFamily: boundedPptxString,
+  fontSize: z.number().positive().nullable(),
+  color: boundedPptxString,
+  bold: z.boolean().nullable(),
+  directFontFamily: boundedPptxString,
+  directFontSize: z.number().positive().nullable(),
+  directColor: boundedPptxString,
+  directBold: z.boolean().nullable(),
+  fontFamilySource: boundedPptxString,
+  fontSizeSource: boundedPptxString,
+  colorSource: boundedPptxString,
+  boldSource: boundedPptxString,
+}).strict();
+
+const pptxShapeTextPage = z.object({
+  schema: z.literal('tiwater.pptx-shape-text-page/v1'),
+  file: z.string(),
+  inputSha256: z.string().regex(/^[a-f0-9]{64}$/),
+  shape: pptxSlideShapeIdentity,
+  receipt: pptxShapeTextPageSummary,
+  segments: z.array(pptxShapeTextSegment).max(4),
+}).strict();
+
 function docxObservationOutput(tool) {
   return z.object({
     tool: z.literal(tool),
@@ -435,6 +539,14 @@ const docxReadObjectOutput = docxObservationOutput('docx_read_object').extend({
 }).strict();
 
 const tools = [
+  {
+    name: 'docx_create',
+    effectKind: 'document-create',
+    description: 'Create one new minimal standards-valid DOCX containing one empty paragraph. The result is a current native document that can be populated incrementally with the ordinary DOCX object operations. The provider chooses no business wording, template, layout mapping, or target structure and never overwrites an existing path.',
+    inputSchema: inputContract('docx_create'),
+    outputSchema: fixedCreateOutput('docx_create'),
+    handler: (args, tool) => fixedCreate(tool, args, docxCandidates),
+  },
   {
     name: 'docx_inspect',
     evidenceRole: 'document-observation',
@@ -705,6 +817,28 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: pptxExportJson,
   },
+  {
+    name: 'pptx_read_slide',
+    description: 'List one selected PPTX slide as bounded pages of compact native shape identities in z-order. Each identity includes its shape id, kind, geometry, text preview, object counts, placeholder facts, media identity, and whether it contains a table. The receipt reports the selected slide, its layout and master paths, remaining shapes, and the next offset. Continue only when another shape on this slide is needed; use pptx_read_shape for bounded text and effective formatting of one selected shape. Set returnContent true to return the selected page when it fits the response limit. Provide output to store the same complete selected page as an immutable artifact. These channels are independent and may be used together; at least one is required. This tool does not select templates, assign business roles, infer repairs, or inspect another slide.',
+    inputSchema: inputContract('pptx_read_slide'),
+    outputSchema: largeResultOutput('pptx_read_slide').extend({
+      summary: pptxSlidePageSummary,
+      content: pptxSlidePage.optional(),
+    }).strict(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: pptxReadSlide,
+  },
+  {
+    name: 'pptx_read_shape',
+    description: 'Read one native PPTX shape selected from pptx_read_slide as bounded text segments. Each segment retains its run and paragraph identity, text offset, paragraph alignment, effective text formatting, direct formatting, and formatting source. Long run text is split without changing its native run identity. The receipt reports remaining segments and the next offset. Continue only when another segment of this shape is needed. Set returnContent true to return the selected page when it fits the response limit. Provide output to store the same complete selected page as an immutable artifact. These channels are independent and may be used together; at least one is required. This tool does not choose formatting, derive repairs, or inspect another shape.',
+    inputSchema: inputContract('pptx_read_shape'),
+    outputSchema: largeResultOutput('pptx_read_shape').extend({
+      summary: pptxShapeTextPageSummary,
+      content: pptxShapeTextPage.optional(),
+    }).strict(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: pptxReadShape,
+  },
   {
     name: 'pptx_apply_template',
     effectKind: 'document-mutation',
@@ -1238,6 +1372,36 @@ async function fixedEdit(tool, args, candidates) {
   });
 }
 
+async function fixedCreate(tool, args, candidates) {
+  const publishedContract = {
+    name: tool.name,
+    inputSchema: inputContractSchema(tool.name),
+    annotations: tool.annotations,
+    _meta: effectKindMetadata(tool.effectKind),
+  };
+  const bindings = documentCreateFileArguments(publishedContract, args);
+  const output = path.resolve(bindings.effectiveOutput);
+  const receiptOutput = path.resolve(requireString(args.receiptOutput, 'receiptOutput'));
+  await requireNewFile(output, 'output');
+  await requireNewFile(receiptOutput, 'receiptOutput');
+  return withTempJsonFile(args, async requestPath => {
+    const result = await runJsonCandidateChain(candidates, [tool.name, requestPath], { allowedExitCodes: [0, 1] });
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim()
+        || `${tool.name} failed with exit code ${result.code}`;
+      throw new Error(detail);
+    }
+    if (result.json?.tool !== tool.name) throw new Error(`${tool.name} returned a mismatched tool identity`);
+    await requireReturnedArtifact(result.json.receipt, receiptOutput, 'receipt');
+    await requireReturnedArtifact(result.json.output, output, 'output');
+    if (result.json.summary?.pass !== true
+        || result.json.summary?.operationCount !== 1 || result.json.summary?.appliedCount !== 1) {
+      throw new Error(`${tool.name} returned invalid creation evidence`);
+    }
+    return { ...result.json, runtime: commandRuntime(result) };
+  });
+}
+
 async function docxCompare(args) {
   const baseline = path.resolve(requireString(args.baseline, 'baseline'));
   const updated = path.resolve(requireString(args.updated, 'updated'));
@@ -1396,6 +1560,36 @@ async function pptxExportJson(args) {
   return deliverLargeJsonResult({ tool: 'pptx_export_json', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input] });
 }
 
+async function pptxReadSlide(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  return withTempJsonFile(args, async requestPath => {
+    const result = await runJsonCandidateChain(pptxCandidates, ['pptx_read_slide', requestPath]);
+    return deliverLargeJsonResult({
+      tool: 'pptx_read_slide',
+      args,
+      runtime: commandRuntime(result),
+      payload: result.json,
+      sourcePaths: [input],
+      summary: result.json.receipt,
+    });
+  });
+}
+
+async function pptxReadShape(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  return withTempJsonFile(args, async requestPath => {
+    const result = await runJsonCandidateChain(pptxCandidates, ['pptx_read_shape', requestPath]);
+    return deliverLargeJsonResult({
+      tool: 'pptx_read_shape',
+      args,
+      runtime: commandRuntime(result),
+      payload: result.json,
+      sourcePaths: [input],
+      summary: result.json.receipt,
+    });
+  });
+}
+
 async function pptxValidate(args) {
   const input = path.resolve(requireString(args.input, 'input'));
   const result = await runJsonCandidateChain(pptxCandidates, ['validate', input], { allowedExitCodes: [0, 1] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.21.38",
+  "version": "0.21.39",
   "description": "Published MCP distribution for independent Tiwater Office, PDF, and Text document capabilities",
   "type": "module",
   "license": "MIT",

package/pdf/contracts/tiwater-pdf-provider-contract-manifest-v1.json

@@ -2,7 +2,7 @@
   "schema": "tiwater.pdf-provider-contract-manifest/v1",
   "provider": {
     "id": "@tiwater/office-mcp",
-    "version": "0.21.38"
+    "version": "0.21.39"
   },
   "runtime": {
     "command": "tiwater-pdf"

package/text/contracts/tiwater-text-provider-contract-manifest-v1.json

@@ -2,7 +2,7 @@
   "schema": "tiwater.text-provider-contract-manifest/v1",
   "provider": {
     "id": "@tiwater/office-mcp",
-    "version": "0.21.38"
+    "version": "0.21.39"
   },
   "tools": [
     {