@sylphx/pdf-reader-mcp 2.1.0 → 2.3.0

package/README.md

@@ -593,6 +593,63 @@ Restart MCP client completely.
 
 ---
 
+## 🌐 HTTP Transport (Remote Access)
+
+By default, PDF Reader MCP uses stdio transport for local use. You can also run it as an HTTP server for remote access from multiple machines.
+
+### Quick Start
+
+```bash
+# Run as HTTP server on port 8080
+MCP_TRANSPORT=http npx @sylphx/pdf-reader-mcp
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_TRANSPORT` | `stdio` | Transport type: `stdio` or `http` |
+| `MCP_HTTP_PORT` | `8080` | HTTP server port |
+| `MCP_HTTP_HOST` | `0.0.0.0` | HTTP server hostname |
+| `MCP_API_KEY` | - | Optional API key for authentication |
+
+### Docker Deployment
+
+```dockerfile
+FROM oven/bun:1
+WORKDIR /app
+RUN bun add @sylphx/pdf-reader-mcp
+ENV MCP_TRANSPORT=http
+ENV MCP_HTTP_PORT=8080
+EXPOSE 8080
+CMD ["bun", "node_modules/@sylphx/pdf-reader-mcp/dist/index.js"]
+```
+
+### MCP Client Configuration (HTTP)
+
+```json
+{
+  "servers": {
+    "pdf-reader": {
+      "type": "http",
+      "url": "https://your-server.com/mcp",
+      "headers": {
+        "X-API-Key": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/mcp` | POST | JSON-RPC endpoint |
+| `/mcp/health` | GET | Health check |
+
+---
+
 ## 🏗️ Architecture
 
 ### Tech Stack
@@ -772,12 +829,11 @@ Special thanks to the open source community ❤️
 This project uses the following [@sylphx](https://github.com/SylphxAI) packages:
 
 - [@sylphx/mcp-server-sdk](https://github.com/SylphxAI/mcp-server-sdk) - MCP server framework
+- [@sylphx/vex](https://github.com/SylphxAI/vex) - Schema validation
 - [@sylphx/biome-config](https://github.com/SylphxAI/biome-config) - Biome configuration
 - [@sylphx/tsconfig](https://github.com/SylphxAI/tsconfig) - TypeScript configuration
 - [@sylphx/bump](https://github.com/SylphxAI/bump) - Version management
 - [@sylphx/doctor](https://github.com/SylphxAI/doctor) - Project health checker
-- [@sylphx/leaf](https://github.com/SylphxAI/leaf) - Documentation framework
-- [@sylphx/leaf-theme-default](https://github.com/SylphxAI/leaf-theme-default) - Documentation theme
 
 ---
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createServer, stdio } from "@sylphx/mcp-server-sdk";
+import { createServer, http, stdio } from "@sylphx/mcp-server-sdk";
 
 // src/handlers/readPdf.ts
 import { image, text, tool, toolError } from "@sylphx/mcp-server-sdk";
@@ -462,6 +462,280 @@ var determinePagesToProcess = (targetPages, totalPages, includeFullText) => {
   return { pagesToProcess: [], invalidPages: [] };
 };
 
+// src/pdf/tableExtractor.ts
+var logger5 = createLogger("TableExtractor");
+var Y_TOLERANCE = 5;
+var COLUMN_GAP_THRESHOLD = 15;
+var MIN_ROWS = 2;
+var MIN_COLS = 2;
+var MIN_ROW_ITEMS = 2;
+var extractTextItemsWithPositions = async (page) => {
+  const textContent = await page.getTextContent();
+  const items = [];
+  for (const item of textContent.items) {
+    const textItem = item;
+    if (!textItem.str.trim())
+      continue;
+    if (!textItem.transform || textItem.transform.length < 6)
+      continue;
+    const x = textItem.transform[4];
+    const y = textItem.transform[5];
+    if (x === undefined || y === undefined)
+      continue;
+    items.push({
+      text: textItem.str,
+      x,
+      y,
+      width: textItem.width ?? textItem.str.length * 6
+    });
+  }
+  return items;
+};
+var clusterByY = (items, tolerance = Y_TOLERANCE) => {
+  if (items.length === 0)
+    return [];
+  const sorted = [...items].sort((a, b) => b.y - a.y);
+  const firstItem = sorted[0];
+  if (!firstItem)
+    return [];
+  const rows = [];
+  let currentRow = { y: firstItem.y, items: [firstItem] };
+  for (let i = 1;i < sorted.length; i++) {
+    const item = sorted[i];
+    if (!item)
+      continue;
+    const yDiff = Math.abs(currentRow.y - item.y);
+    if (yDiff <= tolerance) {
+      currentRow.items.push(item);
+    } else {
+      rows.push(currentRow);
+      currentRow = { y: item.y, items: [item] };
+    }
+  }
+  rows.push(currentRow);
+  for (const row of rows) {
+    row.items.sort((a, b) => a.x - b.x);
+  }
+  return rows;
+};
+var detectColumnBoundaries = (rows, gapThreshold = COLUMN_GAP_THRESHOLD) => {
+  if (rows.length === 0)
+    return [];
+  const allXPositions = [];
+  for (const row of rows) {
+    for (const item of row.items) {
+      allXPositions.push(item.x);
+    }
+  }
+  if (allXPositions.length === 0)
+    return [];
+  allXPositions.sort((a, b) => a - b);
+  const firstX = allXPositions[0];
+  if (firstX === undefined)
+    return [];
+  const boundaries = [firstX];
+  for (let i = 1;i < allXPositions.length; i++) {
+    const current = allXPositions[i];
+    const previous = allXPositions[i - 1];
+    if (current === undefined || previous === undefined)
+      continue;
+    const gap = current - previous;
+    if (gap >= gapThreshold) {
+      boundaries.push(current);
+    }
+  }
+  return boundaries;
+};
+var assignToColumns = (row, columnBoundaries, tolerance = COLUMN_GAP_THRESHOLD / 2) => {
+  const cells = new Array(columnBoundaries.length).fill("");
+  for (const item of row.items) {
+    let colIndex = 0;
+    for (let i = columnBoundaries.length - 1;i >= 0; i--) {
+      const boundary = columnBoundaries[i];
+      if (boundary !== undefined && item.x >= boundary - tolerance) {
+        colIndex = i;
+        break;
+      }
+    }
+    const current = cells[colIndex];
+    cells[colIndex] = current ? `${current} ${item.text}` : item.text;
+  }
+  return cells;
+};
+var calculateConfidence = (rows, columnBoundaries) => {
+  if (rows.length < MIN_ROWS || columnBoundaries.length < MIN_COLS) {
+    return 0;
+  }
+  let score = 0;
+  let checks = 0;
+  for (const row of rows) {
+    const itemsPerColumn = new Set;
+    for (const item of row.items) {
+      for (let i = columnBoundaries.length - 1;i >= 0; i--) {
+        const boundary = columnBoundaries[i];
+        if (boundary !== undefined && item.x >= boundary - COLUMN_GAP_THRESHOLD / 2) {
+          itemsPerColumn.add(i);
+          break;
+        }
+      }
+    }
+    score += itemsPerColumn.size / columnBoundaries.length;
+    checks++;
+  }
+  if (rows.length >= 2) {
+    const spacings = [];
+    for (let i = 1;i < rows.length; i++) {
+      const prevRow = rows[i - 1];
+      const currRow = rows[i];
+      if (prevRow && currRow) {
+        spacings.push(Math.abs(prevRow.y - currRow.y));
+      }
+    }
+    if (spacings.length > 0) {
+      const avgSpacing = spacings.reduce((a, b) => a + b, 0) / spacings.length;
+      const variance = spacings.reduce((sum, s) => sum + (s - avgSpacing) ** 2, 0) / spacings.length;
+      const stdDev = Math.sqrt(variance);
+      const regularityScore = avgSpacing > 0 ? Math.max(0, 1 - stdDev / avgSpacing) : 0;
+      score += regularityScore;
+      checks++;
+    }
+  }
+  return checks > 0 ? Math.min(1, score / checks) : 0;
+};
+var identifyTableRegions = (rows) => {
+  const regions = [];
+  const candidateRows = rows.filter((row) => row.items.length >= MIN_ROW_ITEMS);
+  if (candidateRows.length < MIN_ROWS) {
+    return regions;
+  }
+  const columnBoundaries = detectColumnBoundaries(candidateRows);
+  if (columnBoundaries.length < MIN_COLS) {
+    return regions;
+  }
+  let currentRegion = [];
+  for (const row of candidateRows) {
+    const alignedItems = row.items.filter((item) => {
+      return columnBoundaries.some((boundary) => Math.abs(item.x - boundary) < COLUMN_GAP_THRESHOLD);
+    });
+    if (alignedItems.length >= MIN_COLS - 1) {
+      currentRegion.push(row);
+    } else if (currentRegion.length >= MIN_ROWS) {
+      const firstRow = currentRegion[0];
+      const lastRow = currentRegion[currentRegion.length - 1];
+      if (firstRow && lastRow) {
+        regions.push({
+          rows: currentRegion,
+          columnBoundaries,
+          startY: firstRow.y,
+          endY: lastRow.y
+        });
+      }
+      currentRegion = [];
+    } else {
+      currentRegion = [];
+    }
+  }
+  if (currentRegion.length >= MIN_ROWS) {
+    const firstRow = currentRegion[0];
+    const lastRow = currentRegion[currentRegion.length - 1];
+    if (firstRow && lastRow) {
+      regions.push({
+        rows: currentRegion,
+        columnBoundaries,
+        startY: firstRow.y,
+        endY: lastRow.y
+      });
+    }
+  }
+  return regions;
+};
+var extractTablesFromPage = async (page, pageNum) => {
+  const tables = [];
+  try {
+    const textItems = await extractTextItemsWithPositions(page);
+    if (textItems.length === 0) {
+      return tables;
+    }
+    const rows = clusterByY(textItems);
+    const tableRegions = identifyTableRegions(rows);
+    for (let tableIndex = 0;tableIndex < tableRegions.length; tableIndex++) {
+      const region = tableRegions[tableIndex];
+      if (!region)
+        continue;
+      const tableRows = [];
+      for (const row of region.rows) {
+        const cells = assignToColumns(row, region.columnBoundaries);
+        tableRows.push(cells);
+      }
+      const confidence = calculateConfidence(region.rows, region.columnBoundaries);
+      if (confidence >= 0.3) {
+        tables.push({
+          page: pageNum,
+          tableIndex,
+          rows: tableRows,
+          rowCount: tableRows.length,
+          colCount: region.columnBoundaries.length,
+          confidence: Math.round(confidence * 100) / 100
+        });
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger5.warn("Error extracting tables from page", { pageNum, error: message });
+  }
+  return tables;
+};
+var extractTables = async (pdfDocument, pagesToProcess) => {
+  const allTables = [];
+  for (const pageNum of pagesToProcess) {
+    try {
+      const page = await pdfDocument.getPage(pageNum);
+      const pageTables = await extractTablesFromPage(page, pageNum);
+      allTables.push(...pageTables);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger5.warn("Error getting page for table extraction", { pageNum, error: message });
+    }
+  }
+  return allTables;
+};
+var tableToMarkdown = (table) => {
+  if (table.rows.length === 0)
+    return "";
+  const lines = [];
+  const headerRow = table.rows[0];
+  if (!headerRow)
+    return "";
+  lines.push(`| ${headerRow.map((cell) => cell.trim() || " ").join(" | ")} |`);
+  lines.push(`| ${headerRow.map(() => "---").join(" | ")} |`);
+  for (let i = 1;i < table.rows.length; i++) {
+    const row = table.rows[i];
+    if (!row)
+      continue;
+    const paddedRow = [...row];
+    while (paddedRow.length < headerRow.length) {
+      paddedRow.push("");
+    }
+    lines.push(`| ${paddedRow.map((cell) => cell.trim() || " ").join(" | ")} |`);
+  }
+  return lines.join(`
+`);
+};
+var tablesToMarkdown = (tables) => {
+  if (tables.length === 0)
+    return "";
+  const sections = ["## Extracted Tables", ""];
+  for (const table of tables) {
+    sections.push(`### Page ${table.page}, Table ${table.tableIndex + 1}`);
+    sections.push(`*Confidence: ${(table.confidence * 100).toFixed(0)}%*`);
+    sections.push("");
+    sections.push(tableToMarkdown(table));
+    sections.push("");
+  }
+  return sections.join(`
+`);
+};
+
 // src/schemas/readPdf.ts
 import {
   array,
@@ -487,11 +761,12 @@ var readPdfArgsSchema = object({
   include_full_text: optional(bool(description("Include the full text content of each PDF (only if 'pages' is not specified for that source)."))),
   include_metadata: optional(bool(description("Include metadata and info objects for each PDF."))),
   include_page_count: optional(bool(description("Include the total number of pages for each PDF."))),
-  include_images: optional(bool(description("Extract and include embedded images from the PDF pages as base64-encoded data.")))
+  include_images: optional(bool(description("Extract and include embedded images from the PDF pages as base64-encoded data."))),
+  include_tables: optional(bool(description("Detect and extract tables from PDF pages. Uses spatial clustering of text coordinates to identify tabular structures.")))
 });
 
 // src/handlers/readPdf.ts
-var logger5 = createLogger("ReadPdf");
+var logger6 = createLogger("ReadPdf");
 var processSingleSource = async (source, options) => {
   const sourceDescription = source.path ?? source.url ?? "unknown source";
   let individualResult = { source: sourceDescription, success: false };
@@ -509,7 +784,16 @@ var processSingleSource = async (source, options) => {
       output.warnings = warnings;
     }
     if (pagesToProcess.length > 0) {
-      const pageContents = await Promise.all(pagesToProcess.map((pageNum) => extractPageContent(pdfDocument, pageNum, options.includeImages, sourceDescription)));
+      const MAX_CONCURRENT_PAGES = 5;
+      const pageContents = [];
+      for (let i = 0;i < pagesToProcess.length; i += MAX_CONCURRENT_PAGES) {
+        const batch = pagesToProcess.slice(i, i + MAX_CONCURRENT_PAGES);
+        const batchResults = await Promise.all(batch.map((pageNum) => extractPageContent(pdfDocument, pageNum, options.includeImages, sourceDescription)));
+        pageContents.push(...batchResults);
+        if (i + MAX_CONCURRENT_PAGES < pagesToProcess.length) {
+          await new Promise((resolve) => setImmediate(resolve));
+        }
+      }
       output.page_contents = pageContents.map((items, idx) => ({
         page: pagesToProcess[idx],
         items
@@ -531,6 +815,12 @@ var processSingleSource = async (source, options) => {
           output.images = extractedImages;
         }
       }
+      if (options.includeTables) {
+        const extractedTables = await extractTables(pdfDocument, pagesToProcess);
+        if (extractedTables.length > 0) {
+          output.tables = extractedTables;
+        }
+      }
     }
     individualResult = { ...individualResult, data: output, success: true };
   } catch (error) {
@@ -549,21 +839,29 @@ var processSingleSource = async (source, options) => {
         await pdfDocument.destroy();
       } catch (destroyError) {
         const message = destroyError instanceof Error ? destroyError.message : String(destroyError);
-        logger5.warn("Error destroying PDF document", { sourceDescription, error: message });
+        logger6.warn("Error destroying PDF document", { sourceDescription, error: message });
       }
     }
   }
   return individualResult;
 };
 var readPdf = tool().description("Reads content/metadata/images from one or more PDFs (local/URL). Each source can specify pages to extract.").input(readPdfArgsSchema).handler(async ({ input }) => {
-  const { sources, include_full_text, include_metadata, include_page_count, include_images } = input;
+  const {
+    sources,
+    include_full_text,
+    include_metadata,
+    include_page_count,
+    include_images,
+    include_tables
+  } = input;
   const MAX_CONCURRENT_SOURCES = 3;
   const results = [];
   const options = {
     includeFullText: include_full_text ?? false,
     includeMetadata: include_metadata ?? true,
     includePageCount: include_page_count ?? true,
-    includeImages: include_images ?? false
+    includeImages: include_images ?? false,
+    includeTables: include_tables ?? false
   };
   for (let i = 0;i < sources.length; i += MAX_CONCURRENT_SOURCES) {
     const batch = sources.slice(i, i + MAX_CONCURRENT_SOURCES);
@@ -578,18 +876,27 @@ var readPdf = tool().description("Reads content/metadata/images from one or more
   const content = [];
   const resultsForJson = results.map((result) => {
     if (result.data) {
-      const { images, page_contents, ...dataWithoutBinaryContent } = result.data;
+      const { images, page_contents, tables, ...dataWithoutBinaryContent } = result.data;
+      const processedData = { ...dataWithoutBinaryContent };
       if (images) {
-        const imageInfo = images.map((img) => ({
+        processedData["image_info"] = images.map((img) => ({
           page: img.page,
           index: img.index,
           width: img.width,
           height: img.height,
           format: img.format
         }));
-        return { ...result, data: { ...dataWithoutBinaryContent, image_info: imageInfo } };
       }
-      return { ...result, data: dataWithoutBinaryContent };
+      if (tables && tables.length > 0) {
+        processedData["table_info"] = tables.map((tbl) => ({
+          page: tbl.page,
+          tableIndex: tbl.tableIndex,
+          rowCount: tbl.rowCount,
+          colCount: tbl.colCount,
+          confidence: tbl.confidence
+        }));
+      }
+      return { ...result, data: processedData };
     }
     return result;
   });
@@ -598,29 +905,72 @@ var readPdf = tool().description("Reads content/metadata/images from one or more
     if (!result.success || !result.data?.page_contents)
       continue;
     for (const pageContent of result.data.page_contents) {
+      const pageTextParts = [];
+      const pageImages = [];
       for (const item of pageContent.items) {
         if (item.type === "text" && item.textContent) {
-          content.push(text(item.textContent));
+          pageTextParts.push(item.textContent);
         } else if (item.type === "image" && item.imageData) {
-          content.push(image(item.imageData.data, "image/png"));
+          pageImages.push(item.imageData);
         }
       }
+      if (pageTextParts.length > 0) {
+        content.push(text(`[Page ${pageContent.page}]
+${pageTextParts.join(`
+`)}`));
+      }
+      for (const img of pageImages) {
+        content.push(image(img.data, "image/png"));
+      }
+    }
+  }
+  if (options.includeTables) {
+    const allTables = [];
+    for (const result of results) {
+      if (result.success && result.data?.tables) {
+        allTables.push(...result.data.tables);
+      }
+    }
+    if (allTables.length > 0) {
+      const markdownTables = tablesToMarkdown(allTables);
+      content.push(text(markdownTables));
     }
   }
   return content;
 });
 
 // src/index.ts
+var transportType = process.env["MCP_TRANSPORT"] ?? "stdio";
+var httpPort = Number.parseInt(process.env["MCP_HTTP_PORT"] ?? "8080", 10);
+var httpHost = process.env["MCP_HTTP_HOST"] ?? "0.0.0.0";
+var apiKey = process.env["MCP_API_KEY"];
+function createTransport() {
+  if (transportType === "http") {
+    return http({
+      port: httpPort,
+      hostname: httpHost,
+      cors: "*"
+    });
+  }
+  return stdio();
+}
 var server = createServer({
   name: "pdf-reader-mcp",
-  version: "1.3.0",
+  version: "2.1.0",
   instructions: "MCP Server for reading PDF files and extracting text, metadata, images, and page information.",
   tools: { read_pdf: readPdf },
-  transport: stdio()
+  transport: createTransport()
 });
 async function main() {
   await server.start();
-  if (process.env["DEBUG_MCP"]) {
+  if (transportType === "http") {
+    console.log(`[PDF Reader MCP] Server running on http://${httpHost}:${httpPort}/mcp`);
+    console.log(`[PDF Reader MCP] Health check: http://${httpHost}:${httpPort}/mcp/health`);
+    if (apiKey) {
+      console.log("[PDF Reader MCP] API key authentication enabled (X-API-Key header)");
+    }
+    console.log("[PDF Reader MCP] Project root:", process.cwd());
+  } else if (process.env["DEBUG_MCP"]) {
     console.error("[PDF Reader MCP] Server running on stdio");
     console.error("[PDF Reader MCP] Project root:", process.cwd());
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/pdf-reader-mcp",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "An MCP server providing tools to read PDF files.",
   "type": "module",
   "bin": {
@@ -12,9 +12,7 @@
     "LICENSE"
   ],
   "exports": {
-    ".": {
-      "import": "./dist/index.js"
-    }
+    ".": "./dist/index.js"
   },
   "publishConfig": {
     "access": "public"
@@ -45,7 +43,7 @@
     "tool"
   ],
   "scripts": {
-    "build": "bunup",
+    "build": "bunup --no-dts",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
     "test": "bun test",
@@ -58,9 +56,9 @@
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "validate": "bun run check && bun run test",
-    "docs:dev": "bunx @sylphx/leaf dev docs",
-    "docs:build": "bunx @sylphx/leaf build docs",
-    "docs:preview": "bunx @sylphx/leaf preview docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
     "benchmark": "bun bench",
@@ -77,28 +75,25 @@
     "pdfjs-dist": "^5.4.449",
     "pngjs": "^7.0.0"
   },
+  "overrides": {
+    "esbuild": "^0.25.0",
+    "preact": "^10.28.2"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.8",
-    "@solidjs/router": "^0.15.4",
     "@sylphx/biome-config": "^0.4.1",
     "@sylphx/bump": "^1.6.1",
     "@sylphx/doctor": "^1.32.1",
-    "@sylphx/leaf": "^1.0.0",
-    "@sylphx/leaf-theme-default": "^1.0.0",
     "@sylphx/tsconfig": "^0.3.1",
     "@types/glob": "^8.1.0",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.3",
     "@types/pngjs": "^6.0.5",
-    "bunup": "^0.16.10",
+    "bunup": "0.16.10",
     "lefthook": "^2.0.7",
-    "solid-js": "^1.9.10",
     "typedoc": "^0.28.15",
     "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.9.3",
-    "vite": "^7.2.6"
+    "vitepress": "^1.6.4"
   },
-  "packageManager": "bun@1.3.1",
-  "overrides": {
-    "js-yaml": "^4.1.0"
-  }
+  "packageManager": "bun@1.3.1"
 }