@tiwater/office-mcp 0.21.28 → 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.28"
+    "version": "0.21.29"
   },
   "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.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();