@tiwater/office-mcp 0.21.27 → 0.21.29

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.27"
+    "version": "0.21.29"
   },
   "tools": [
     {
@@ -456,6 +456,17 @@
         "sha256": "9ae4a846a8ca5b9059dcfd2a589e9872a2ab8d4ba3a118a513f3e05462f923d0"
       }
     },
+    {
+      "name": "xlsx_read_range",
+      "providerContract": {
+        "source": "packages/xlsx-cli/contracts/mcp-input/xlsx_read_range.schema.json",
+        "sha256": "04b0ce1b912047f774fbbbb6ba7cf55e5e53a9b74d6f027d9c21b4d6d7397225"
+      },
+      "inputContract": {
+        "path": "office/contracts/xlsx_read_range.schema.json",
+        "sha256": "04b0ce1b912047f774fbbbb6ba7cf55e5e53a9b74d6f027d9c21b4d6d7397225"
+      }
+    },
     {
       "name": "xlsx_set_cell_number_format",
       "providerContract": {

package/office/contracts/xlsx_read_range.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tiwater.office-mcp-input/xlsx_read_range/v1",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Current XLSX workbook. Convert legacy XLS before selecting Open XML cells.",
+      "x-tiwater-file-role": "read"
+    },
+    "sheet": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Exact current worksheet name returned by workbook observation."
+    },
+    "range": {
+      "type": "string",
+      "pattern": "^[A-Za-z]{1,3}[1-9][0-9]*(?::[A-Za-z]{1,3}[1-9][0-9]*)?$",
+      "description": "Explicit native A1 cell or rectangular range. A single cell is a one-cell range."
+    },
+    "offset": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Zero-based cell offset in row-major order within the selected range. Continue only when another selected cell is needed."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 256,
+      "description": "Maximum selected cells in this bounded page."
+    },
+    "returnContent": {
+      "type": "boolean",
+      "description": "Return this selected technical page directly when it fits the response limit. May be combined with output."
+    },
+    "output": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional immutable JSON artifact path for this selected technical page. May be combined with returnContent.",
+      "x-tiwater-file-role": "write"
+    }
+  },
+  "required": ["input", "sheet", "range", "limit", "returnContent"],
+  "additionalProperties": false
+}

package/office/index.mjs

@@ -202,6 +202,67 @@ const xlsxInspectionSummary = z.object({
   }).strict()).max(6),
 }).strict();
 
+const xlsxRangePageSummary = z.object({
+  schema: z.literal('tiwater.xlsx-range-page-receipt/v1'),
+  totalCellCount: z.number().int().nonnegative(),
+  returnedCellCount: z.number().int().nonnegative(),
+  remaining: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative().nullable(),
+}).strict();
+
+const xlsxRangePage = z.object({
+  schema: z.literal('tiwater.xlsx-range-page/v1'),
+  toolVersion: z.string(),
+  file: z.string(),
+  inputSha256: z.string().regex(/^[a-f0-9]{64}$/),
+  sheet: z.string(),
+  range: z.string(),
+  receipt: xlsxRangePageSummary,
+  cells: z.array(z.object({
+    reference: z.string(),
+    row: z.number().int().positive(),
+    column: z.number().int().positive(),
+    physical: z.boolean(),
+    rawValue: z.string().nullable(),
+    formattedValue: z.string().nullable(),
+    valueType: z.string().nullable(),
+    normalizedValue: z.object({ kind: z.string(), iso8601: z.string().nullable() }).strict().nullable(),
+    formula: z.object({
+      text: z.string(),
+      type: z.string().nullable(),
+      sharedIndex: z.number().int().nonnegative().nullable(),
+      reference: z.string().nullable(),
+    }).strict().nullable(),
+    style: z.object({
+      styleIndex: z.number().int().nonnegative(),
+      numberFormatId: z.number().int().nonnegative(),
+      numberFormatCode: z.string().nullable(),
+      fontId: z.number().int().nonnegative(),
+      fillId: z.number().int().nonnegative(),
+      borderId: z.number().int().nonnegative(),
+      horizontalAlignment: z.string().nullable(),
+      verticalAlignment: z.string().nullable(),
+      wrapText: z.boolean(),
+      bold: z.boolean(),
+    }).strict().nullable(),
+    richTextRuns: z.array(z.object({
+      text: z.string(),
+      fontName: z.string().nullable(),
+      color: z.string().nullable(),
+      underline: z.string().nullable(),
+      bold: z.boolean(),
+      italic: z.boolean(),
+    }).strict()).nullable(),
+    mergedRange: z.string().nullable(),
+    mergeOwner: z.string().nullable(),
+  }).strict()).max(256),
+}).strict();
+
+const xlsxRangeReadOutput = largeResultOutput('xlsx_read_range').extend({
+  summary: xlsxRangePageSummary,
+  content: xlsxRangePage.optional(),
+}).strict();
+
 const pptxInspectionSummary = z.object({
   slideCount: z.number().int().nonnegative(),
   masterCount: z.number().int().nonnegative(),
@@ -580,6 +641,14 @@ const tools = [
     annotations: { readOnlyHint: true, idempotentHint: true },
     handler: xlsxExportJson,
   },
+  {
+    name: 'xlsx_read_range',
+    description: 'Read one explicit native A1 cell or rectangular range from one current XLSX worksheet. Pages use a row-major cell offset and return physical presence, raw and formatted values, normalized value type, formula metadata, style, rich text, and merged-range ownership. The receipt always reports remaining cells and the next offset. Continue only when another selected cell is needed. Set returnContent true to return the selected page when it fits the response limit. Provide output to store the same complete selected page as an immutable artifact. These channels are independent and may be used together; at least one is required. This tool does not infer regions, headers, records, field meanings, or business mappings; convert legacy XLS before reading Open XML cells.',
+    inputSchema: inputContract('xlsx_read_range'),
+    outputSchema: xlsxRangeReadOutput,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    handler: xlsxReadRange,
+  },
   ...fixedToolDefinitions(xlsxFixedTools),
   {
     name: 'xlsx_validate',
@@ -1202,6 +1271,21 @@ async function xlsxExportJson(args) {
   return deliverLargeJsonResult({ tool: 'xlsx_export_json', args, runtime: commandRuntime(result), payload: result.json, sourcePaths: [input] });
 }
 
+async function xlsxReadRange(args) {
+  const input = path.resolve(requireString(args.input, 'input'));
+  return withTempJsonFile(args, async requestPath => {
+    const result = await runJsonCandidateChain(xlsxCandidates, ['xlsx_read_range', requestPath]);
+    return deliverLargeJsonResult({
+      tool: 'xlsx_read_range',
+      args,
+      runtime: commandRuntime(result),
+      payload: result.json,
+      sourcePaths: [input],
+      summary: result.json.receipt,
+    });
+  });
+}
+
 async function xlsxValidate(args) {
   const input = path.resolve(requireString(args.input, 'input'));
   const result = await runJsonCandidateChain(xlsxCandidates, ['validate', input], { allowedExitCodes: [0, 1] });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiwater/office-mcp",
-  "version": "0.21.27",
-  "description": "Published MCP server for Tiwater Office document capabilities",
+  "version": "0.21.29",
+  "description": "Published MCP distribution for independent Tiwater Office and PDF document capabilities",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,8 @@
     "directory": "servers"
   },
   "bin": {
-    "tiwater-office-mcp": "office/index.mjs"
+    "tiwater-office-mcp": "office/index.mjs",
+    "tiwater-pdf-mcp": "pdf/index.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -19,11 +20,15 @@
     "_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"
   ],
   "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.29"
+  },
+  "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();