@tiwater/office-mcp 0.21.29 → 0.21.30

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.30"
   },
   "tools": [
     {

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

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,24 @@
+{
+  "$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"
+    }
+  },
+  "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.30"
+  },
+  "tools": [
+    {
+      "name": "text_inspect",
+      "providerContract": {
+        "source": "servers/text/provider-contracts/text_inspect.schema.json",
+        "sha256": "41d463771e4cf5d0c9377ba70a139ca043ca9542f074c7d6425f0b711cfa50b8"
+      },
+      "inputContract": {
+        "path": "text/contracts/text_inspect.schema.json",
+        "sha256": "41d463771e4cf5d0c9377ba70a139ca043ca9542f074c7d6425f0b711cfa50b8"
+      }
+    },
+    {
+      "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,180 @@
+#!/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 { 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',
+    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,
+        },
+      },
+      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('');
+}