@research-copilot/mcp-pdf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ldm2060
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @research-copilot/mcp-pdf
+
+MCP server for PDF text and metadata extraction using [unpdf](https://github.com/unjs/unpdf).
+
+## Installation
+
+```bash
+npx @research-copilot/mcp-pdf
+```
+
+Or via MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "research-pdf": {
+      "command": "npx",
+      "args": ["-y", "@research-copilot/mcp-pdf"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `pdf_extract_text`
+
+Extract text content from a PDF file.
+
+**Inputs:**
+- `path` (string, required) - Absolute path to PDF file
+- `mergePages` (boolean, optional) - Merge all pages into single text block (default: true)
+
+**Returns:**
+- `text` (string) - Extracted text content
+- `totalPages` (number) - Total page count
+
+**Note:** unpdf extracts text in content-stream order. For two-column academic papers, text from both columns may be interleaved. Page numbers are advisory.
+
+### `pdf_extract_metadata`
+
+Extract PDF metadata (page count, document info).
+
+**Inputs:**
+- `path` (string, required) - Absolute path to PDF file
+
+**Returns:**
+- `totalPages` (number) - Total page count
+- `info` (object) - Document metadata (title, author, creation date, etc.)
+
+## Implementation
+
+- Built with [unpdf](https://github.com/unjs/unpdf) for PDF parsing
+- Uses Mozilla PDF.js under the hood
+- Text extraction is coarse (content-stream order, not reading order)
+- Suitable for simple text extraction; complex layouts may need specialized tools
+
+## License
+
+MIT

package/dist/mcp-pdf.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+// bin/mcp-pdf.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { readFileSync } from "fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/extract.ts
+import { extractText as unpdfExtractText, getDocumentProxy, getMeta } from "unpdf";
+async function extractText(data, opts) {
+  const mergePages = opts?.mergePages ?? true;
+  const bytes = data.slice();
+  if (mergePages) {
+    const { text: text2, totalPages: totalPages2 } = await unpdfExtractText(bytes, { mergePages: true });
+    return { text: text2, totalPages: totalPages2 };
+  }
+  const { text, totalPages } = await unpdfExtractText(bytes, { mergePages: false });
+  return { text: text.join("\n\n"), totalPages };
+}
+async function extractMetadata(data) {
+  const pdf = await getDocumentProxy(data.slice());
+  const totalPages = pdf.numPages;
+  const { info } = await getMeta(data.slice());
+  return { totalPages, info: info ?? {} };
+}
+
+// src/server.ts
+function readPdf(path) {
+  const buf = readFileSync(path);
+  return new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+}
+function createServer() {
+  const server = new McpServer({
+    name: "mcp-pdf",
+    version: "0.0.0"
+  });
+  server.registerTool(
+    "pdf_extract_text",
+    {
+      title: "Extract PDF text",
+      description: "Extract the text of a local PDF file. Coarse extraction (content-stream order); two-column layouts may interleave. Extracted numbers are advisory.",
+      inputSchema: { path: z.string().describe("Absolute or relative path to a local PDF file") }
+    },
+    async ({ path }) => {
+      try {
+        const data = readPdf(path);
+        const { text, totalPages } = await extractText(data);
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: { text, totalPages }
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [{ type: "text", text: `pdf_extract_text failed for "${path}": ${message}` }]
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "pdf_extract_metadata",
+    {
+      title: "Extract PDF metadata",
+      description: "Extract metadata (page count and the PDF info dictionary) from a local PDF file.",
+      inputSchema: { path: z.string().describe("Absolute or relative path to a local PDF file") }
+    },
+    async ({ path }) => {
+      try {
+        const data = readPdf(path);
+        const { totalPages, info } = await extractMetadata(data);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ totalPages, info }, null, 2) }],
+          structuredContent: { totalPages, info }
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            { type: "text", text: `pdf_extract_metadata failed for "${path}": ${message}` }
+          ]
+        };
+      }
+    }
+  );
+  return server;
+}
+
+// bin/mcp-pdf.ts
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`mcp-pdf: fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@research-copilot/mcp-pdf",
+  "version": "1.0.0",
+  "description": "MCP server for PDF extraction",
+  "type": "module",
+  "bin": {
+    "mcp-pdf": "./dist/mcp-pdf.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "pdf",
+    "extraction"
+  ],
+  "author": "ldm2060",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ldm2060/research_copilot.git",
+    "directory": "packages/mcp-pdf"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "unpdf": "^0.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "pdf-lib": "^1.17.1"
+  },
+  "scripts": {
+    "build": "tsup bin/mcp-pdf.ts --format esm"
+  }
+}