@tiwater/office-mcp 0.21.28 → 0.21.30

package/_shared/large-json-result.mjs

@@ -16,7 +16,7 @@ export function resultChannels(args) {
   return { returnContent, output };
 }
 
-export async function deliverLargeJsonResult({ tool, args, runtime, payload, sourcePaths, summary }) {
+export async function deliverLargeJsonResult({ tool, args, runtime, payload, sourcePaths, summary, identity }) {
   const channels = resultChannels(args);
   const contentBytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
   const contentReturned = channels.returnContent && contentBytes <= returnedContentBudgetBytes;
@@ -38,6 +38,7 @@ export async function deliverLargeJsonResult({ tool, args, runtime, payload, sou
       contentWritten: channels.output !== null,
     },
     ...(summary === undefined ? {} : { summary }),
+    ...(identity === undefined ? {} : { identity }),
     ...(contentReturned ? { content: payload } : {}),
   };
 }

package/_shared/mcp-stdio.mjs

@@ -0,0 +1,154 @@
+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 (Number.isInteger(error.code) && error.message) {
+    return toError(error.code, error.message, error.data);
+  }
+  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) });
+      }
+    }
+  }
+}

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.28"
+    "version": "0.21.30"
   },
   "tools": [
     {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.21.28",
-  "description": "Published MCP server for Tiwater Office document capabilities",
+  "version": "0.21.30",
+  "description": "Published MCP distribution for independent Tiwater Office, PDF, and Text document capabilities",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,9 @@
     "directory": "servers"
   },
   "bin": {
-    "tiwater-office-mcp": "office/index.mjs"
+    "tiwater-office-mcp": "office/index.mjs",
+    "tiwater-pdf-mcp": "pdf/index.mjs",
+    "tiwater-text-mcp": "text/index.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -19,11 +21,20 @@
     "_shared/tool-runtime.mjs",
     "_shared/large-json-result.mjs",
     "_shared/output-write-lock.mjs",
+    "_shared/mcp-stdio.mjs",
     "office/index.mjs",
     "office/docx-object-identity.mjs",
     "office/README.md",
     "office/contracts/tiwater-office-provider-contract-manifest-v1.json",
-    "office/contracts/*.schema.json"
+    "office/contracts/*.schema.json",
+    "pdf/index.mjs",
+    "pdf/README.md",
+    "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/README.md

@@ -0,0 +1,30 @@
+# Tiwater PDF MCP
+
+Published, Agent-facing stdio MCP server for PDF inspection, table extraction,
+and OCR. It is a separate executable, process, and tool surface from the Office
+MCP, distributed in the same npm package so both use one trusted release path.
+
+## Tools
+
+- `pdf_inspect`
+- `pdf_extract_tables`
+- `pdf_find_table`
+- `pdf_extract_table_details`
+- `pdf_ocr` (pinned Aliyun `qwen3.8-max`; per-invocation Supen credential)
+
+Every tool is read-only and records the exact input PDF identity. Read results
+can be retained in immutable JSON artifacts. `pdf_inspect` always requires that
+durable artifact and separately returns a bounded document identity without
+traversing page content.
+
+## Install and run
+
+```bash
+npm install --global @tiwater/office-mcp
+tiwater-pdf-mcp
+```
+
+The server invokes the independently published `tiwater-pdf` executable from
+`PATH`. It does not fall back to a repository checkout. OCR credentials are
+provided to that child for one invocation by the runtime environment; the MCP
+does not read or persist provider credentials.

package/pdf/contracts/pdf_extract_table_details.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current PDF revision.",
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete result directly when it fits the published response limit."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path for the immutable JSON observation artifact. An identical replay may reuse identical bytes; different content is never written over it.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    },
+    "pages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "integer",
+        "minimum": 1
+      }
+    }
+  },
+  "required": [
+    "input",
+    "returnContent"
+  ],
+  "additionalProperties": false
+}

package/pdf/contracts/pdf_extract_tables.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current PDF revision.",
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete result directly when it fits the published response limit."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path for the immutable JSON observation artifact. An identical replay may reuse identical bytes; different content is never written over it.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    },
+    "pages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "integer",
+        "minimum": 1
+      }
+    },
+    "autoSpan": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "input",
+    "returnContent"
+  ],
+  "additionalProperties": false
+}

package/pdf/contracts/pdf_find_table.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current PDF revision.",
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete result directly when it fits the published response limit."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path for the immutable JSON observation artifact. An identical replay may reuse identical bytes; different content is never written over it.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "autoSpan": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "input",
+    "name",
+    "returnContent"
+  ],
+  "additionalProperties": false
+}

package/pdf/contracts/pdf_inspect.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current PDF revision.",
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete result directly when it fits the published response limit."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path for the immutable JSON observation artifact. An identical replay may reuse identical bytes; different content is never written over it.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    }
+  },
+  "required": [
+    "input",
+    "output"
+  ],
+  "additionalProperties": false
+}

package/pdf/contracts/pdf_ocr.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the current PDF revision.",
+      "x-tiwater-file-role": "read"
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return the complete result directly when it fits the published response limit."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path for the immutable JSON observation artifact. An identical replay may reuse identical bytes; different content is never written over it.",
+      "x-tiwater-file-role": "write",
+      "x-tiwater-file-effect": false
+    },
+    "pages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "integer",
+        "minimum": 1
+      }
+    }
+  },
+  "required": [
+    "input",
+    "returnContent"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,47 @@
+{
+  "schema": "tiwater.pdf-provider-contract-manifest/v1",
+  "provider": {
+    "id": "@tiwater/office-mcp",
+    "version": "0.21.30"
+  },
+  "runtime": {
+    "command": "tiwater-pdf"
+  },
+  "tools": [
+    {
+      "name": "pdf_inspect",
+      "inputContract": {
+        "path": "contracts/pdf_inspect.schema.json",
+        "sha256": "0b397cca1351bfe79af8bb2b81e107c9d566f7772f3c6f7eea54d26048116eeb"
+      }
+    },
+    {
+      "name": "pdf_extract_tables",
+      "inputContract": {
+        "path": "contracts/pdf_extract_tables.schema.json",
+        "sha256": "2ff2d609964e0d2c6cc84c8f8caf6002de3ce8ce4b78e28a99a9e0430502d3b4"
+      }
+    },
+    {
+      "name": "pdf_find_table",
+      "inputContract": {
+        "path": "contracts/pdf_find_table.schema.json",
+        "sha256": "1bb441cedaeb78a3776096718d1ce51f29e7832e19ed0a43f9138c45a400bd18"
+      }
+    },
+    {
+      "name": "pdf_ocr",
+      "inputContract": {
+        "path": "contracts/pdf_ocr.schema.json",
+        "sha256": "8910ece3646ca0154ab8d18bd602d2fc9666067543d4cdc2b999a8d8543aada2"
+      }
+    },
+    {
+      "name": "pdf_extract_table_details",
+      "inputContract": {
+        "path": "contracts/pdf_extract_table_details.schema.json",
+        "sha256": "8910ece3646ca0154ab8d18bd602d2fc9666067543d4cdc2b999a8d8543aada2"
+      }
+    }
+  ]
+}

package/pdf/index.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { deliverLargeJsonResult } from '../_shared/large-json-result.mjs';
+import { McpStdioServer } from '../_shared/mcp-stdio.mjs';
+import {
+  commandCandidate,
+  createToolResult,
+  requireString,
+  runJsonCandidateChain,
+} from '../_shared/tool-runtime.mjs';
+
+const pdfRoot = path.dirname(fileURLToPath(import.meta.url));
+const distributionRoot = path.resolve(pdfRoot, '..');
+const packageJson = readJson(path.join(distributionRoot, 'package.json'));
+const manifest = readJson(path.join(
+  pdfRoot, 'contracts', 'tiwater-pdf-provider-contract-manifest-v1.json',
+));
+if (manifest.schema !== 'tiwater.pdf-provider-contract-manifest/v1'
+  || manifest.provider?.id !== packageJson.name
+  || manifest.provider?.version !== packageJson.version) {
+  throw new Error('pdf-provider-contract-manifest-invalid');
+}
+
+const pdfCandidates = [commandCandidate('tiwater-pdf')];
+const artifactSchema = {
+  type: 'object',
+  properties: {
+    path: { type: 'string' },
+    sha256: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+    bytes: { type: 'integer', minimum: 1 },
+  },
+  required: ['path', 'sha256', 'bytes'],
+  additionalProperties: false,
+};
+const receiptSchema = {
+  type: 'object',
+  properties: {
+    contentBytes: { type: 'integer', minimum: 0 },
+    contentReturned: { type: 'boolean' },
+    contentWritten: { type: 'boolean' },
+  },
+  required: ['contentBytes', 'contentReturned', 'contentWritten'],
+  additionalProperties: false,
+};
+const largeResultOutputSchema = {
+  type: 'object',
+  properties: {
+    tool: { type: 'string' },
+    runtime: {
+      type: 'object',
+      properties: {
+        command: { type: 'string' },
+        arguments: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['command', 'arguments'],
+      additionalProperties: false,
+    },
+    sources: { type: 'array', minItems: 1, maxItems: 1, items: artifactSchema },
+    returnContent: { type: 'boolean' },
+    artifact: { anyOf: [artifactSchema, { type: 'null' }] },
+    receipt: receiptSchema,
+    content: {},
+  },
+  required: ['tool', 'runtime', 'sources', 'returnContent', 'artifact', 'receipt'],
+  additionalProperties: false,
+};
+const pageIdentitySchema = {
+  type: 'object',
+  properties: {
+    page: { type: 'integer', minimum: 1 },
+    width: { type: 'number', exclusiveMinimum: 0 },
+    height: { type: 'number', exclusiveMinimum: 0 },
+    imageCount: { type: 'integer', minimum: 0 },
+    wordCount: { type: 'integer', minimum: 0 },
+    imageOnly: { type: 'boolean' },
+  },
+  required: ['page', 'width', 'height', 'imageCount', 'wordCount', 'imageOnly'],
+  additionalProperties: false,
+};
+const inspectIdentitySchema = {
+  type: 'object',
+  properties: {
+    format: { const: 'pdf' },
+    pageCount: { type: 'integer', minimum: 1 },
+    title: { type: ['string', 'null'] },
+    author: { type: ['string', 'null'] },
+    subject: { type: ['string', 'null'] },
+    imageCount: { type: 'integer', minimum: 0 },
+    wordCount: { type: 'integer', minimum: 0 },
+    scannedPageCount: { type: 'integer', minimum: 0 },
+    imageOnly: { type: 'boolean' },
+    openingPages: { type: 'array', maxItems: 3, items: pageIdentitySchema },
+  },
+  required: [
+    'format', 'pageCount', 'title', 'author', 'subject', 'imageCount', 'wordCount',
+    'scannedPageCount', 'imageOnly', 'openingPages',
+  ],
+  additionalProperties: false,
+};
+const inspectOutputSchema = structuredClone(largeResultOutputSchema);
+inspectOutputSchema.properties.identity = inspectIdentitySchema;
+inspectOutputSchema.required.push('identity');
+
+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,
+  }],
+  ['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.',
+    outputSchema: largeResultOutputSchema,
+  }],
+  ['pdf_find_table', {
+    description: 'Find a caller-named table in one current PDF without deciding its business role. Set returnContent true to return complete bounded content; provide output to retain the complete immutable result. At least one result channel is required.',
+    outputSchema: largeResultOutputSchema,
+  }],
+  ['pdf_ocr', {
+    description: 'Observe selected current PDF pages through the fixed Aliyun qwen3.8-max OCR model and per-invocation Supen credential. Set returnContent true to return complete bounded content; provide output to retain the complete immutable result. At least one result channel is required.',
+    outputSchema: largeResultOutputSchema,
+  }],
+  ['pdf_extract_table_details', {
+    description: 'Read visual table cells, text spans, fonts, colors, and line evidence from selected current PDF pages. Set returnContent true to return complete bounded content; provide output to retain the complete immutable result. At least one result channel is required.',
+    outputSchema: largeResultOutputSchema,
+  }],
+]);
+
+const tools = manifest.tools.map((entry) => {
+  const definition = definitions.get(entry.name);
+  if (!definition) throw new Error(`pdf-provider-tool-definition-missing:${entry.name}`);
+  const contractPath = path.join(pdfRoot, entry.inputContract.path);
+  const bytes = readFileSync(contractPath);
+  if (createHash('sha256').update(bytes).digest('hex') !== entry.inputContract.sha256) {
+    throw new Error(`pdf-provider-input-contract-hash-invalid:${entry.name}`);
+  }
+  return {
+    name: entry.name,
+    description: definition.description,
+    inputSchema: JSON.parse(bytes.toString('utf8')),
+    outputSchema: definition.outputSchema,
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  };
+});
+
+async function callTool(name, args) {
+  switch (name) {
+    case 'pdf_inspect': return createToolResult(await pdfInspect(args));
+    case 'pdf_extract_tables': return createToolResult(await pdfExtractTables(args));
+    case 'pdf_find_table': return createToolResult(await pdfFindTable(args));
+    case 'pdf_ocr': return createToolResult(await pdfOcr(args));
+    case 'pdf_extract_table_details': return createToolResult(await pdfExtractTableDetails(args));
+    default: throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32601 });
+  }
+}
+
+async function pdfInspect(args) {
+  rejectUnexpectedArgs(args, ['input', 'returnContent', 'output']);
+  const input = path.resolve(requireString(args.input, 'input'));
+  requireString(args.output, 'output');
+  const result = await runJsonCandidateChain(pdfCandidates, ['inspect', input, '--json']);
+  const payload = result.json;
+  const document = payload?.document ?? payload;
+  if (!document || !Number.isInteger(document.pages) || document.pages < 1) {
+    throw new Error('pdf-inspect-runtime-result-invalid');
+  }
+  const metadata = document.metadata && typeof document.metadata === 'object' ? document.metadata : {};
+  const identity = {
+    format: 'pdf',
+    pageCount: document.pages,
+    title: nullableText(metadata.title),
+    author: nullableText(metadata.author),
+    subject: nullableText(metadata.subject),
+    imageCount: nonnegativeInteger(document.image_count),
+    wordCount: nonnegativeInteger(document.word_count),
+    scannedPageCount: nonnegativeInteger(document.scanned_page_count),
+    imageOnly: document.image_only === true,
+    openingPages: (Array.isArray(document.page_sizes) ? document.page_sizes : []).slice(0, 3)
+      .map((page) => ({
+        page: positiveInteger(page.page),
+        width: positiveNumber(page.width),
+        height: positiveNumber(page.height),
+        imageCount: nonnegativeInteger(page.image_count),
+        wordCount: nonnegativeInteger(page.word_count),
+        imageOnly: page.image_only === true,
+      })),
+  };
+  return deliverLargeJsonResult({
+    tool: 'pdf_inspect', args, runtime: commandRuntime(result), payload, sourcePaths: [input], identity,
+  });
+}
+
+async function pdfExtractTables(args) {
+  rejectUnexpectedArgs(args, ['input', 'pages', 'autoSpan', 'returnContent', 'output']);
+  const input = path.resolve(requireString(args.input, 'input'));
+  const commandArgs = ['extract-tables', input];
+  appendPdfFlags(commandArgs, args);
+  commandArgs.push('--json');
+  const result = await runJsonCandidateChain(pdfCandidates, commandArgs);
+  return deliverLargeJsonResult({
+    tool: 'pdf_extract_tables', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input],
+  });
+}
+
+async function pdfFindTable(args) {
+  rejectUnexpectedArgs(args, ['input', 'name', 'autoSpan', 'returnContent', 'output']);
+  const input = path.resolve(requireString(args.input, 'input'));
+  const commandArgs = ['find-table', input, requireString(args.name, 'name')];
+  appendPdfFlags(commandArgs, args);
+  commandArgs.push('--json');
+  const result = await runJsonCandidateChain(pdfCandidates, commandArgs);
+  return deliverLargeJsonResult({
+    tool: 'pdf_find_table', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input],
+  });
+}
+
+async function pdfExtractTableDetails(args) {
+  rejectUnexpectedArgs(args, ['input', 'pages', 'returnContent', 'output']);
+  const input = path.resolve(requireString(args.input, 'input'));
+  const commandArgs = ['extract-table-details', input];
+  appendPages(commandArgs, args.pages);
+  commandArgs.push('--json');
+  const result = await runJsonCandidateChain(pdfCandidates, commandArgs);
+  return deliverLargeJsonResult({
+    tool: 'pdf_extract_table_details', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input],
+  });
+}
+
+async function pdfOcr(args) {
+  rejectUnexpectedArgs(args, ['input', 'output', 'pages', 'returnContent']);
+  const input = path.resolve(requireString(args.input, 'input'));
+  const commandArgs = ['ocr', input, '--provider', 'llm', '--llm-model', 'qwen3.8-max'];
+  appendPages(commandArgs, args.pages);
+  commandArgs.push('--json');
+  const result = await runJsonCandidateChain(pdfCandidates, commandArgs);
+  return deliverLargeJsonResult({
+    tool: 'pdf_ocr', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input],
+  });
+}
+
+function rejectUnexpectedArgs(args, allowed) {
+  const unexpected = Object.keys(args).filter(key => !allowed.includes(key));
+  if (unexpected.length > 0) {
+    throw Object.assign(new Error(`Unexpected arguments: ${unexpected.join(', ')}`), { code: -32602 });
+  }
+}
+
+function appendPdfFlags(commandArgs, args) {
+  appendPages(commandArgs, args.pages);
+  if (args.autoSpan === true) commandArgs.push('--auto-span');
+}
+
+function appendPages(commandArgs, pages) {
+  if (Array.isArray(pages) && pages.length > 0) commandArgs.push('--pages', pages.join(','));
+}
+
+function commandRuntime(result) {
+  return { command: result.command, arguments: result.args };
+}
+
+function nullableText(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function nonnegativeInteger(value) {
+  if (!Number.isInteger(value) || value < 0) throw new Error('pdf-inspect-runtime-result-invalid');
+  return value;
+}
+
+function positiveInteger(value) {
+  if (!Number.isInteger(value) || value < 1) throw new Error('pdf-inspect-runtime-result-invalid');
+  return value;
+}
+
+function positiveNumber(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error('pdf-inspect-runtime-result-invalid');
+  }
+  return value;
+}
+
+function readJson(file) {
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+const server = new McpStdioServer({
+  name: 'tiwater-pdf',
+  version: packageJson.version,
+  instructions: [
+    'Generic PDF inspection, deterministic table extraction, and OCR fixed to Aliyun qwen3.8-max through the per-invocation Supen Gateway credential.',
+    'Every output path is an immutable observation artifact identity: an identical request may replay identical bytes, while every different result uses a different path.',
+    'PDF tools report technical observations only and never assign business roles, source dispositions, or delivery decisions.',
+  ].join(' '),
+  tools,
+  callTool,
+  logger: message => process.stderr.write(`${message}\n`),
+});
+
+server.start();

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('');
+}