@tiwater/office-mcp 0.21.29 → 0.21.31

package/_shared/evidence-role.mjs

@@ -0,0 +1,123 @@
+export const evidenceRoleMetadataKey = 'x-tiwater-evidence-role';
+export const evidenceRoleSchema = 'tiwater.provider-evidence-role/v1';
+
+const evidenceRoles = new Set([
+  'document-observation',
+  'final-readback',
+  'native-render',
+]);
+
+export function evidenceRoleMetadata(role) {
+  if (!evidenceRoles.has(role)) throw new Error(`unsupported-evidence-role:${role}`);
+  return {
+    [evidenceRoleMetadataKey]: {
+      schema: evidenceRoleSchema,
+      role,
+    },
+  };
+}
+
+export function assertEvidenceToolContract(tool, expectedRole) {
+  const metadata = tool?._meta?.[evidenceRoleMetadataKey];
+  if (!metadata || Object.keys(metadata).sort().join(',') !== 'role,schema'
+      || metadata.schema !== evidenceRoleSchema || metadata.role !== expectedRole) {
+    throw new Error(`evidence-role-metadata-invalid:${tool?.name || 'unnamed'}`);
+  }
+  const bindings = fileBindings(tool.inputSchema);
+  if (!bindings.some(binding => binding.role === 'read')) {
+    throw new Error(`evidence-role-source-binding-missing:${tool.name}`);
+  }
+  if (!tool.outputSchema || typeof tool.outputSchema !== 'object') {
+    throw new Error(`evidence-role-output-schema-missing:${tool.name}`);
+  }
+
+  if (expectedRole === 'native-render') {
+    assertAnnotations(tool, false, false);
+    if (!bindings.some(binding => binding.role === 'write' && binding.effect)
+        || !bindings.some(binding => binding.role === 'write' && !binding.effect)
+        || !requiredArtifact(tool.outputSchema, 'receipt')) {
+      throw new Error(`native-render-evidence-contract-invalid:${tool.name}`);
+    }
+    return;
+  }
+
+  assertAnnotations(tool, true, true);
+  const writes = bindings.filter(binding => binding.role === 'write');
+  if (writes.length < 1 || writes.some(binding => binding.effect)) {
+    throw new Error(`read-evidence-artifact-binding-invalid:${tool.name}`);
+  }
+  if (!sourceIdentity(tool.outputSchema) || !requiredArtifact(tool.outputSchema, 'artifact')) {
+    throw new Error(`read-evidence-output-binding-invalid:${tool.name}`);
+  }
+  if (expectedRole === 'document-observation') {
+    const identity = requiredObject(tool.outputSchema, 'identity') || requiredObject(tool.outputSchema, 'summary');
+    if (!identity || unboundedArrays(identity).length > 0) {
+      throw new Error(`document-observation-identity-unbounded:${tool.name}`);
+    }
+  } else if (!requiredObject(tool.outputSchema, 'receipt')) {
+    throw new Error(`final-readback-receipt-missing:${tool.name}`);
+  }
+}
+
+function assertAnnotations(tool, readOnlyHint, idempotentHint) {
+  const annotations = tool.annotations || {};
+  if (annotations.readOnlyHint !== readOnlyHint
+      || annotations.idempotentHint !== idempotentHint
+      || annotations.destructiveHint !== false
+      || annotations.openWorldHint !== false) {
+    throw new Error(`evidence-role-annotations-invalid:${tool.name}`);
+  }
+}
+
+function fileBindings(schema) {
+  const bindings = [];
+  function visit(node) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    if (node['x-tiwater-file-role'] === 'read' || node['x-tiwater-file-role'] === 'write') {
+      bindings.push({
+        role: node['x-tiwater-file-role'],
+        effect: node['x-tiwater-file-role'] === 'write' && node['x-tiwater-file-effect'] !== false,
+      });
+    }
+    for (const child of Object.values(node.properties || {})) visit(child);
+    if (node.items) visit(node.items);
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+      for (const child of node[keyword] || []) visit(child);
+    }
+  }
+  visit(schema);
+  return bindings;
+}
+
+function requiredObject(schema, property) {
+  const value = schema?.properties?.[property];
+  return schema?.required?.includes(property) && value?.type === 'object' ? value : null;
+}
+
+function artifactShape(schema) {
+  const candidate = schema?.anyOf?.find(value => value?.type === 'object') || schema;
+  return candidate?.type === 'object'
+    && ['path', 'sha256', 'bytes'].every(property => candidate.required?.includes(property));
+}
+
+function requiredArtifact(schema, property) {
+  return schema?.required?.includes(property) && artifactShape(schema?.properties?.[property]);
+}
+
+function sourceIdentity(schema) {
+  if (requiredArtifact(schema, 'source')) return true;
+  const sources = schema?.properties?.sources;
+  return schema?.required?.includes('sources') && sources?.type === 'array'
+    && Number.isInteger(sources.maxItems) && artifactShape(sources.items);
+}
+
+function unboundedArrays(schema, location = '$', found = []) {
+  if (Array.isArray(schema)) {
+    schema.forEach((child, index) => unboundedArrays(child, `${location}[${index}]`, found));
+    return found;
+  }
+  if (!schema || typeof schema !== 'object') return found;
+  if (schema.type === 'array' && !Number.isInteger(schema.maxItems)) found.push(location);
+  for (const [key, child] of Object.entries(schema)) unboundedArrays(child, `${location}.${key}`, found);
+  return found;
+}

package/office/contracts/docx_export_json.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "Absolute path for a new JSON artifact inside the caller-authorized output directory. Existing files are never overwritten.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     }
   },
   "required": [

package/office/contracts/docx_inspect.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "Optional absolute path for retaining the complete observation inside the caller-authorized output directory; existing files are never overwritten. May be combined with returnContent.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     }
   },
   "required": [

package/office/contracts/pptx_export_json.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "New JSON artifact path. Existing files are never overwritten.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     }
   },
   "required": [

package/office/contracts/pptx_inspect.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "New JSON artifact path. Existing files are never overwritten.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     }
   },
   "required": [

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.29"
+    "version": "0.21.31"
   },
   "tools": [
     {
@@ -64,11 +64,11 @@
       "name": "docx_export_json",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_export_json.schema.json",
-        "sha256": "0556937d649a1248947019f23c005786046f576e64a844f057745933f5821cd7"
+        "sha256": "995eb1a5a8992e2a2186f2d7621b5eea7875eecd78ce153e77964d2942db2211"
       },
       "inputContract": {
         "path": "office/contracts/docx_export_json.schema.json",
-        "sha256": "0556937d649a1248947019f23c005786046f576e64a844f057745933f5821cd7"
+        "sha256": "995eb1a5a8992e2a2186f2d7621b5eea7875eecd78ce153e77964d2942db2211"
       }
     },
     {
@@ -108,11 +108,11 @@
       "name": "docx_inspect",
       "providerContract": {
         "source": "packages/docx-cli/contracts/mcp-input/docx_inspect.schema.json",
-        "sha256": "5e112a2dbed5a9b1cc1874de50100d181c654d2482e81f229edaff87085079c3"
+        "sha256": "a7d00a4caa5983d5dbf210eade9ebcc345afaa9f6c72dcae37978447ad180259"
       },
       "inputContract": {
         "path": "office/contracts/docx_inspect.schema.json",
-        "sha256": "5e112a2dbed5a9b1cc1874de50100d181c654d2482e81f229edaff87085079c3"
+        "sha256": "a7d00a4caa5983d5dbf210eade9ebcc345afaa9f6c72dcae37978447ad180259"
       }
     },
     {
@@ -328,22 +328,22 @@
       "name": "pptx_export_json",
       "providerContract": {
         "source": "packages/pptx-cli/contracts/mcp-input/pptx_export_json.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       },
       "inputContract": {
         "path": "office/contracts/pptx_export_json.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       }
     },
     {
       "name": "pptx_inspect",
       "providerContract": {
         "source": "packages/pptx-cli/contracts/mcp-input/pptx_inspect.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       },
       "inputContract": {
         "path": "office/contracts/pptx_inspect.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       }
     },
     {
@@ -427,11 +427,11 @@
       "name": "xlsx_export_json",
       "providerContract": {
         "source": "packages/xlsx-cli/contracts/mcp-input/xlsx_export_json.schema.json",
-        "sha256": "98055d552649ed5162bc9045344b1a309ff1de6a4bbf9d7ecca7ec9135de827c"
+        "sha256": "3943fa01506e5b9ea1cb0ecfd13fc484c16ec96245af462c9a6a37377f2a7a82"
       },
       "inputContract": {
         "path": "office/contracts/xlsx_export_json.schema.json",
-        "sha256": "98055d552649ed5162bc9045344b1a309ff1de6a4bbf9d7ecca7ec9135de827c"
+        "sha256": "3943fa01506e5b9ea1cb0ecfd13fc484c16ec96245af462c9a6a37377f2a7a82"
       }
     },
     {
@@ -449,11 +449,11 @@
       "name": "xlsx_inspect",
       "providerContract": {
         "source": "packages/xlsx-cli/contracts/mcp-input/xlsx_inspect.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       },
       "inputContract": {
         "path": "office/contracts/xlsx_inspect.schema.json",
-        "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
+        "sha256": "9cde8fdda335f379d44e60819367b305a2c97c6c0c8fdf2141bf460335e5da84"
       }
     },
     {

package/office/contracts/xlsx_export_json.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "New JSON artifact path. Existing files are never overwritten.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     },
     "resolveMergedCells": {
       "description": "Resolve merged cells to project values.",

package/office/contracts/xlsx_inspect.schema.json

@@ -15,7 +15,8 @@
       "type": "string",
       "minLength": 1,
       "description": "New JSON artifact path. Existing files are never overwritten.",
-      "x-tiwater-file-role": "write"
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
     }
   },
   "required": [

package/office/index.mjs

@@ -23,6 +23,7 @@ import {
   writeJsonArtifact,
 } from '../_shared/large-json-result.mjs';
 import { withOutputWriteLock } from '../_shared/output-write-lock.mjs';
+import { evidenceRoleMetadata } from '../_shared/evidence-role.mjs';
 import { compactDocxObjectIdentity } from './docx-object-identity.mjs';
 
 const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
@@ -424,10 +425,11 @@ const docxReadObjectOutput = docxObservationOutput('docx_read_object').extend({
 const tools = [
   {
     name: 'docx_inspect',
+    evidenceRole: 'document-observation',
     description: 'Inspect one current DOCX for identity and package overview. The response always includes a bounded identity summary. Set returnContent true when that summary is the requested direct result. Provide output to retain the complete machine observation and return its artifact receipt. These channels are independent and may be used together. At least one channel is required. Use list and read operations to traverse selected document objects in native structure order. This overview is not a complete final-document readback; use docx_export_json when a downstream consumer requires the complete body projection.',
     inputSchema: inputContract('docx_inspect'),
     outputSchema: docxInspectionOutput('docx_inspect'),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: docxInspect,
   },
   {
@@ -549,10 +551,11 @@ const tools = [
   },
   {
     name: 'docx_export_json',
+    evidenceRole: 'final-readback',
     description: 'Produce the complete body-only DOCX JSON projection required for final-document readback or another downstream consumer of that format. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required. This does not replace bounded list and read operations during document processing.',
     inputSchema: inputContract('docx_export_json'),
     outputSchema: largeResultOutput('docx_export_json'),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: docxExportJson,
   },
   {
@@ -614,9 +617,11 @@ const tools = [
   },
   {
     name: 'office_render_pdf',
+    evidenceRole: 'native-render',
     description: 'Render a current Office document to PDF with its required native WPS backend and write the complete provider receipt as evidence. The input extension selects Writer, Spreadsheets, or Presentation; fallback rendering is rejected.',
     inputSchema: inputContract('office_render_pdf'),
     outputSchema: nativeRenderOutput,
+    annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
     handler: officeRenderPdf,
   },
   {
@@ -627,18 +632,20 @@ const tools = [
   },
   {
     name: 'xlsx_inspect',
+    evidenceRole: 'document-observation',
     description: 'Inspect a current XLSX workbook or legacy XLS workbook, including workbook structure, exported values, formulas, styles, merged ranges, and published legacy-format conversion evidence. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required.',
     inputSchema: inputContract('xlsx_inspect'),
     outputSchema: largeInspectionOutput('xlsx_inspect', xlsxInspectionSummary),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: xlsxInspect,
   },
   {
     name: 'xlsx_export_json',
+    evidenceRole: 'final-readback',
     description: 'Export workbook sheet data from XLSX as structured JSON. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required.',
     inputSchema: inputContract('xlsx_export_json'),
     outputSchema: largeResultOutput('xlsx_export_json'),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: xlsxExportJson,
   },
   {
@@ -660,18 +667,20 @@ const tools = [
   },
   {
     name: 'pptx_inspect',
+    evidenceRole: 'document-observation',
     description: 'Inspect a PPTX file, including slides, masters, layouts, shapes, transforms, paragraphs, runs, and placeholders. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required.',
     inputSchema: inputContract('pptx_inspect'),
     outputSchema: largeInspectionOutput('pptx_inspect', pptxInspectionSummary),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: pptxInspect,
   },
   {
     name: 'pptx_export_json',
+    evidenceRole: 'final-readback',
     description: 'Export PPTX slide text, notes, and placeholder hints as structured JSON. Set returnContent true to return the complete result when it fits the response limit. Provide output to write the complete result to a new JSON file. The two choices are independent and may be used together; at least one is required.',
     inputSchema: inputContract('pptx_export_json'),
     outputSchema: largeResultOutput('pptx_export_json'),
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
     handler: pptxExportJson,
   },
   {
@@ -727,6 +736,7 @@ function buildServer() {
         inputSchema: tool.inputSchema,
         ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
         ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        ...(tool.evidenceRole ? { _meta: evidenceRoleMetadata(tool.evidenceRole) } : {}),
       },
       async args => {
         const payload = typeof args.output === 'string'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.21.29",
-  "description": "Published MCP distribution for independent Tiwater Office and PDF document capabilities",
+  "version": "0.21.31",
+  "description": "Published MCP distribution for independent Tiwater Office, PDF, and Text document capabilities",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -11,7 +11,8 @@
   },
   "bin": {
     "tiwater-office-mcp": "office/index.mjs",
-    "tiwater-pdf-mcp": "pdf/index.mjs"
+    "tiwater-pdf-mcp": "pdf/index.mjs",
+    "tiwater-text-mcp": "text/index.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -21,6 +22,7 @@
     "_shared/large-json-result.mjs",
     "_shared/output-write-lock.mjs",
     "_shared/mcp-stdio.mjs",
+    "_shared/evidence-role.mjs",
     "office/index.mjs",
     "office/docx-object-identity.mjs",
     "office/README.md",
@@ -28,7 +30,12 @@
     "office/contracts/*.schema.json",
     "pdf/index.mjs",
     "pdf/README.md",
-    "pdf/contracts/*.json"
+    "pdf/contracts/*.json",
+    "text/index.mjs",
+    "text/observation.mjs",
+    "text/README.md",
+    "text/contracts/tiwater-text-provider-contract-manifest-v1.json",
+    "text/contracts/*.schema.json"
   ],
   "publishConfig": {
     "access": "public"

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.29"
+    "version": "0.21.31"
   },
   "runtime": {
     "command": "tiwater-pdf"

package/pdf/index.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 
 import { deliverLargeJsonResult } from '../_shared/large-json-result.mjs';
 import { McpStdioServer } from '../_shared/mcp-stdio.mjs';
+import { evidenceRoleMetadata } from '../_shared/evidence-role.mjs';
 import {
   commandCandidate,
   createToolResult,
@@ -110,6 +111,7 @@ const definitions = new Map([
   ['pdf_inspect', {
     description: 'Inspect one current PDF revision. Always retain the complete observation at output and return a bounded identity containing page and document metadata without traversing document content.',
     outputSchema: inspectOutputSchema,
+    evidenceRole: 'document-observation',
   }],
   ['pdf_extract_tables', {
     description: 'Extract tables from selected current PDF pages with deterministic published extraction. Set returnContent true to return complete bounded content; provide output to retain the complete immutable result. At least one result channel is required.',
@@ -142,6 +144,7 @@ const tools = manifest.tools.map((entry) => {
     description: definition.description,
     inputSchema: JSON.parse(bytes.toString('utf8')),
     outputSchema: definition.outputSchema,
+    ...(definition.evidenceRole ? { _meta: evidenceRoleMetadata(definition.evidenceRole) } : {}),
     annotations: {
       readOnlyHint: true,
       idempotentHint: true,

package/text/README.md

@@ -0,0 +1,14 @@
+# tiwater-text-mcp
+
+`tiwater-text-mcp` publishes read-only observation for explicitly supported
+plain-text files. `text_inspect` reports the exact byte identity, lossless
+decoding facts, line count, and bounded opening lines. `text_read_lines` reads
+one explicit zero-based line page and reports its continuation.
+
+Supported inputs are `.txt`, `.text`, `.log`, `.csv`, `.tsv`, `.md`, and
+`.markdown` files encoded as valid UTF-8, UTF-8 with BOM, UTF-16LE with BOM, or
+UTF-16BE with BOM. The provider rejects binary content and never guesses an
+encoding.
+
+The tools do not interpret key-value pairs, records, sections, Markdown, or
+business fields, and never modify or transcode the source.

package/text/contracts/text_inspect.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.text-mcp-input/text_inspect/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete bounded inspection directly."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "New immutable JSON artifact path for the complete inspection.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": ["input", "returnContent", "output"],
+  "additionalProperties": false
+}

package/text/contracts/text_read_lines.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.text-mcp-input/text_read_lines/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "x-tiwater-file-role": "read"
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based line offset in the exact current source revision."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 200,
+      "description": "Maximum number of lines in this bounded page."
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return this selected line 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 line page. May be combined with returnContent.",
+      "x-tiwater-file-role": "write"
+    }
+  },
+  "required": ["input", "offset", "limit", "returnContent"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,31 @@
+{
+  "schema": "tiwater.text-provider-contract-manifest/v1",
+  "provider": {
+    "id": "@tiwater/office-mcp",
+    "version": "0.21.31"
+  },
+  "tools": [
+    {
+      "name": "text_inspect",
+      "providerContract": {
+        "source": "servers/text/provider-contracts/text_inspect.schema.json",
+        "sha256": "7a4af90303d2a0abce66a2e77f83838dbb2ea925edf98b04a80723b92b7f5ec0"
+      },
+      "inputContract": {
+        "path": "text/contracts/text_inspect.schema.json",
+        "sha256": "7a4af90303d2a0abce66a2e77f83838dbb2ea925edf98b04a80723b92b7f5ec0"
+      }
+    },
+    {
+      "name": "text_read_lines",
+      "providerContract": {
+        "source": "servers/text/provider-contracts/text_read_lines.schema.json",
+        "sha256": "0f9202f0b45bbd35b3ba4bebec7776da41f2c8668c7cdece068c44102f518bb6"
+      },
+      "inputContract": {
+        "path": "text/contracts/text_read_lines.schema.json",
+        "sha256": "0f9202f0b45bbd35b3ba4bebec7776da41f2c8668c7cdece068c44102f518bb6"
+      }
+    }
+  ]
+}

package/text/index.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import * as z from 'zod/v4';
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+
+import { createToolResult } from '../_shared/tool-runtime.mjs';
+import { deliverLargeJsonResult } from '../_shared/large-json-result.mjs';
+import { withOutputWriteLock } from '../_shared/output-write-lock.mjs';
+import { evidenceRoleMetadata } from '../_shared/evidence-role.mjs';
+import { inspectText, readTextLines } from './observation.mjs';
+
+const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const contractManifest = JSON.parse(await readFile(
+  new URL('./contracts/tiwater-text-provider-contract-manifest-v1.json', import.meta.url),
+  'utf8',
+));
+if (contractManifest.schema !== 'tiwater.text-provider-contract-manifest/v1'
+    || contractManifest.provider?.id !== packageMetadata.name
+    || contractManifest.provider?.version !== packageMetadata.version) {
+  throw new Error('Text MCP input contract manifest does not match the installed distribution');
+}
+
+const inputContracts = new Map(await Promise.all(contractManifest.tools.map(async entry => {
+  const bytes = await readFile(new URL(`./contracts/${entry.name}.schema.json`, import.meta.url));
+  const hash = createHash('sha256').update(bytes).digest('hex');
+  if (hash !== entry.inputContract.sha256) {
+    throw new Error(`Text MCP input contract hash mismatch: ${entry.name}`);
+  }
+  return [entry.name, z.fromJSONSchema(JSON.parse(bytes.toString('utf8')))];
+})));
+
+const openingLineLimit = 8;
+const artifact = z.object({
+  path: z.string(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  bytes: z.number().int().nonnegative(),
+}).strict();
+const runtimeIdentity = z.object({ command: z.literal('tiwater-text-mcp'), cwd: z.string() }).strict();
+const decoding = z.object({
+  status: z.literal('lossless'),
+  encoding: z.enum(['utf-8', 'utf-16le', 'utf-16be']),
+  bom: z.enum(['none', 'utf-8', 'utf-16le', 'utf-16be']),
+}).strict();
+const lineIdentity = z.object({
+  sourceSha256: z.string().regex(/^[0-9a-f]{64}$/),
+  index: z.number().int().nonnegative(),
+}).strict();
+const terminator = z.enum(['none', 'lf', 'crlf', 'cr']);
+const openingLine = z.object({
+  identity: lineIdentity,
+  textPreview: z.string(),
+  textLength: z.number().int().nonnegative(),
+  terminator,
+}).strict();
+const inspectIdentity = z.object({
+  source: artifact,
+  extension: z.string(),
+  decoding,
+  lineCount: z.number().int().nonnegative(),
+  openingLines: z.array(openingLine).max(openingLineLimit),
+}).strict();
+const linePageReceipt = z.object({
+  schema: z.literal('tiwater.text-line-page-receipt/v1'),
+  totalLineCount: z.number().int().nonnegative(),
+  returnedLineCount: z.number().int().nonnegative(),
+  remaining: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative().nullable(),
+}).strict();
+const textLine = z.object({ identity: lineIdentity, text: z.string(), terminator }).strict();
+const inspectContent = z.object({
+  schema: z.literal('tiwater.text-inspection/v1'),
+  source: artifact,
+  extension: z.string(),
+  decoding,
+  lineCount: z.number().int().nonnegative(),
+  openingLines: z.array(openingLine).max(openingLineLimit),
+}).strict();
+const linePage = z.object({
+  schema: z.literal('tiwater.text-line-page/v1'),
+  source: artifact,
+  extension: z.string(),
+  decoding,
+  receipt: linePageReceipt,
+  lines: z.array(textLine).max(200),
+}).strict();
+
+function largeResultOutput(contentSchema) {
+  return z.object({
+    tool: z.string(),
+    runtime: runtimeIdentity,
+    sources: z.array(artifact).min(1).max(1),
+    returnContent: z.boolean(),
+    artifact: artifact.nullable(),
+    receipt: z.object({
+      contentBytes: z.number().int().nonnegative(),
+      contentReturned: z.boolean(),
+      contentWritten: z.boolean(),
+    }).strict(),
+    content: contentSchema.optional(),
+  }).strict();
+}
+
+const definitions = [
+  {
+    name: 'text_inspect',
+    evidenceRole: 'document-observation',
+    description: 'Inspect one exact supported plain-text revision. Return its byte identity, lossless encoding and BOM facts, line count, and at most eight opening line identities while retaining the complete bounded inspection at output. It does not parse fields, records, key-value pairs, sections, or markup.',
+    outputSchema: largeResultOutput(inspectContent).extend({ identity: inspectIdentity }).strict(),
+    handler: textInspect,
+  },
+  {
+    name: 'text_read_lines',
+    description: 'Read one explicit zero-based line page from one exact supported plain-text revision. The receipt reports remaining lines and nextOffset; continue only when another line is needed. Set returnContent true to return the selected page when it fits the response limit. Provide output to retain the same complete page. These channels are independent and may be used together; at least one is required. Lines retain their exact decoded text and terminator; the provider does not interpret fields, records, key-value pairs, sections, Markdown, or business meaning.',
+    outputSchema: largeResultOutput(linePage).extend({ summary: linePageReceipt }).strict(),
+    handler: textReadLines,
+  },
+];
+
+function buildServer() {
+  const server = new McpServer(
+    { name: 'tiwater-text', version: packageMetadata.version },
+    { instructions: 'Observe only exact supported plain-text bytes and explicit zero-based line pages. A read-only output path is an immutable artifact identity: an identical request may replay it; every different request uses a different path. Callers own all interpretation and business meaning.' },
+  );
+  for (const definition of definitions) {
+    const inputSchema = inputContracts.get(definition.name);
+    if (!inputSchema) throw new Error(`Missing provider-owned Text MCP input contract: ${definition.name}`);
+    server.registerTool(
+      definition.name,
+      {
+        description: definition.description,
+        inputSchema,
+        outputSchema: definition.outputSchema,
+        annotations: {
+          readOnlyHint: true,
+          idempotentHint: true,
+          destructiveHint: false,
+          openWorldHint: false,
+        },
+        ...(definition.evidenceRole ? { _meta: evidenceRoleMetadata(definition.evidenceRole) } : {}),
+      },
+      async args => {
+        const payload = typeof args.output === 'string'
+          ? await withOutputWriteLock(args.output, () => definition.handler(args))
+          : await definition.handler(args);
+        return createToolResult(payload);
+      },
+    );
+  }
+  return server;
+}
+
+async function textInspect(args) {
+  const observation = await inspectText(args.input);
+  const delivered = await deliverLargeJsonResult({
+    tool: 'text_inspect',
+    args,
+    runtime: runtime(),
+    payload: observation.payload,
+    sourcePaths: [observation.input],
+  });
+  return { ...delivered, identity: observation.identity };
+}
+
+async function textReadLines(args) {
+  const observation = await readTextLines(args.input, args.offset, args.limit);
+  const delivered = await deliverLargeJsonResult({
+    tool: 'text_read_lines',
+    args,
+    runtime: runtime(),
+    payload: observation.payload,
+    sourcePaths: [observation.input],
+  });
+  return { ...delivered, summary: observation.receipt };
+}
+
+function runtime() {
+  return { command: 'tiwater-text-mcp', cwd: process.cwd() };
+}
+
+serveStdio(buildServer);

package/text/observation.mjs

@@ -0,0 +1,162 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { fileArtifact } from '../_shared/large-json-result.mjs';
+
+const supportedExtensions = new Set(['.txt', '.text', '.log', '.csv', '.tsv', '.md', '.markdown']);
+const openingLineLimit = 8;
+const openingTextLimit = 160;
+
+export async function inspectText(inputValue) {
+  const observation = await observeText(inputValue);
+  const source = await fileArtifact(observation.input);
+  const openingLines = observation.lines.slice(0, openingLineLimit).map(line => ({
+    identity: { sourceSha256: source.sha256, index: line.index },
+    textPreview: preview(line.text, openingTextLimit),
+    textLength: [...line.text].length,
+    terminator: line.terminator,
+  }));
+  const identity = {
+    source,
+    extension: observation.extension,
+    decoding: observation.decoding,
+    lineCount: observation.lines.length,
+    openingLines,
+  };
+  return {
+    input: observation.input,
+    identity,
+    payload: { schema: 'tiwater.text-inspection/v1', ...identity },
+  };
+}
+
+export async function readTextLines(inputValue, requestedOffset, requestedLimit) {
+  if (!Number.isSafeInteger(requestedOffset) || requestedOffset < 0) {
+    throw Object.assign(new Error('offset must be a non-negative safe integer'), { code: -32602 });
+  }
+  if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > 200) {
+    throw Object.assign(new Error('limit must be a safe integer from 1 through 200'), { code: -32602 });
+  }
+  const observation = await observeText(inputValue);
+  const source = await fileArtifact(observation.input);
+  const offset = Math.min(requestedOffset, observation.lines.length);
+  const selected = observation.lines.slice(offset, offset + requestedLimit);
+  const nextOffset = offset + selected.length < observation.lines.length
+    ? offset + selected.length
+    : null;
+  const receipt = {
+    schema: 'tiwater.text-line-page-receipt/v1',
+    totalLineCount: observation.lines.length,
+    returnedLineCount: selected.length,
+    remaining: observation.lines.length - offset - selected.length,
+    nextOffset,
+  };
+  return {
+    input: observation.input,
+    receipt,
+    payload: {
+      schema: 'tiwater.text-line-page/v1',
+      source,
+      extension: observation.extension,
+      decoding: observation.decoding,
+      receipt,
+      lines: selected.map(line => ({
+        identity: { sourceSha256: source.sha256, index: line.index },
+        text: line.text,
+        terminator: line.terminator,
+      })),
+    },
+  };
+}
+
+export async function observeText(inputValue) {
+  if (typeof inputValue !== 'string' || inputValue.trim() === '') {
+    throw Object.assign(new Error('input must be a non-empty string'), { code: -32602 });
+  }
+  const input = path.resolve(inputValue);
+  const extension = path.extname(input).toLowerCase();
+  if (!supportedExtensions.has(extension)) {
+    throw Object.assign(new Error(`unsupported-plain-text-extension:${extension || '(none)'}`), { code: -32602 });
+  }
+  const bytes = await readFile(input);
+  const decoded = decodeLosslessly(bytes);
+  rejectBinaryControls(decoded.text);
+  return { input, extension, decoding: decoded.decoding, lines: splitLines(decoded.text) };
+}
+
+function decodeLosslessly(bytes) {
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf]))) {
+    return decodeWithRoundTrip(bytes.subarray(3), 'utf-8', 'utf-8');
+  }
+  if (bytes.subarray(0, 2).equals(Buffer.from([0xff, 0xfe]))) {
+    return decodeWithRoundTrip(bytes.subarray(2), 'utf-16le', 'utf-16le');
+  }
+  if (bytes.subarray(0, 2).equals(Buffer.from([0xfe, 0xff]))) {
+    return decodeWithRoundTrip(bytes.subarray(2), 'utf-16be', 'utf-16be');
+  }
+  return decodeWithRoundTrip(bytes, 'utf-8', 'none');
+}
+
+function decodeWithRoundTrip(bytes, encoding, bom) {
+  if ((encoding === 'utf-16le' || encoding === 'utf-16be') && bytes.length % 2 !== 0) {
+    throw Object.assign(new Error(`invalid-${encoding}-byte-length`), { code: -32602 });
+  }
+  let text;
+  try {
+    text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+  } catch {
+    throw Object.assign(new Error(`invalid-${encoding}-sequence`), { code: -32602 });
+  }
+  let encoded = encoding === 'utf-8' ? Buffer.from(text, 'utf8') : Buffer.from(text, 'utf16le');
+  if (encoding === 'utf-16be') encoded = swapUtf16Bytes(encoded);
+  if (!encoded.equals(bytes)) {
+    throw Object.assign(new Error(`non-lossless-${encoding}-decode`), { code: -32602 });
+  }
+  return { text, decoding: { status: 'lossless', encoding, bom } };
+}
+
+function swapUtf16Bytes(bytes) {
+  const swapped = Buffer.allocUnsafe(bytes.length);
+  for (let index = 0; index < bytes.length; index += 2) {
+    swapped[index] = bytes[index + 1];
+    swapped[index + 1] = bytes[index];
+  }
+  return swapped;
+}
+
+function rejectBinaryControls(text) {
+  const binary = [...text].some(character => {
+    const code = character.codePointAt(0);
+    return code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31)
+      || (code >= 127 && code <= 159);
+  });
+  if (binary) throw Object.assign(new Error('binary-control-content-is-not-plain-text'), { code: -32602 });
+}
+
+function splitLines(text) {
+  if (text.length === 0) return [];
+  const lines = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = start;
+    while (end < text.length && text[end] !== '\r' && text[end] !== '\n') end++;
+    let terminator = 'none';
+    let next = end;
+    if (end < text.length) {
+      if (text[end] === '\r' && text[end + 1] === '\n') {
+        terminator = 'crlf';
+        next = end + 2;
+      } else {
+        terminator = text[end] === '\r' ? 'cr' : 'lf';
+        next = end + 1;
+      }
+    }
+    lines.push({ index: lines.length, text: text.slice(start, end), terminator });
+    start = next;
+  }
+  return lines;
+}
+
+function preview(text, limit) {
+  return [...text].slice(0, limit).join('');
+}