PDF Text Extractor MCP

PDF 文本提取器 MCP

一个本地 STDIO MCP 服务，仅提供一个工具：extract_pdf_text。它使用 PDF.js 读取嵌入的文本；对于扫描页面，则回退到英语／德语 OCR，并按文档顺序返回页面级段落。无需 React 应用、HTTP 服务、API 密钥或 PDF 上传。

需要 Node.js 22.19 或更高版本和 npm（node 和 npx 必须在 PATH 中）。

运行已发布的软件包

版本 0.1.1 已发布到 npm。 无需克隆代码仓库或启动 React 应用，即可运行：

npx -y [email protected]

进程会等待 MCP 客户端从 stdin 输入。没有交互式提示。客户端通常会自行启动此命令。

VS Code 配置

将以下内容放入 .vscode/mcp.json，然后从 VS Code 的 MCP 控制项启动服务，并在 Agent 聊天中启用此工具：

{
  "servers": {
    "pdf-text-extractor": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

对于本地开发构建，请在本地构建后使用 "command": "node" 和 "args": ["/absolute/path/to/pdf-text-extractor/mcp/dist/index.js"]。 其他客户端可能使用顶层键 mcpServers，而不是 servers；请遵循该客户端的配置格式。

让客户端提取本地 PDF，或使用以下参数调用 extract_pdf_text：

{ "file_path": "/absolute/path/to/contract.pdf" }

在 Windows 的 JSON 中，使用绝对路径，例如 C:\\Users\\you\\contract.pdf。 该路径指向运行 MCP 服务的计算机上的文件。

结果约定

成功调用会返回 isError: false、一个 JSON 文本内容块，以及 structuredContent 中的同一对象：

{
  "success": true,
  "text": "First page text\n\nSecond page text",
  "page_count": 2,
  "pages_without_text": [],
  "pages": [
    {
      "page_number": 1,
      "method": "embedded",
      "text": "First page text",
      "paragraphs": ["First page text"],
      "warnings": []
    },
    {
      "page_number": 2,
      "method": "ocr",
      "text": "Second page text",
      "paragraphs": ["Second page text"],
      "warnings": []
    }
  ],
  "warnings": []
}

文件错误或提取错误会返回 isError: true，并包含 { "success": false, "text": "", "error": "PDF file was not found." }。 缺失或类型不正确的参数会被 SDK 拒绝，并在开始提取前返回 MCP 工具错误。

原有的 text、page_count 和 pages_without_text 字段仍然可用。 text 会以空行连接非空页面；每个页面的 text 会以空行连接其 paragraphs，并保留段落内的换行符。 page_number 和 pages_without_text 使用从 1 开始的页码。 method 的值为 embedded、ocr；如果未能提取任何文本且 OCR 失败，则为 none。如果 OCR 尝试已完成但未发现文本，则会报告 ocr 并附带警告。 顶层的 warnings 会重复列出页面警告，并包含对应页码。 success: true 表示 PDF 已处理；如有部分结果，请参阅警告。

仅接受带有 PDF 文件头的常规 .pdf 文件，最大 25 MiB。 文件缺失、无法读取、无效、超出大小限制或受密码保护时会产生错误。 服务读取文件但不会修改文件，不会执行 shell 命令，也不会为提取内容发出网络请求。诊断信息会写入 stderr；stdout 仅用于 MCP 消息。PDF 内容绝不会写入日志。

限制

没有嵌入正文文本的页面（包括只有页眉或页脚的页面）会使用 OCR。 正文文本少于 40 个字符且包含图像的页面也会使用 OCR。 OCR 成功后会替换页面的嵌入文本，以避免页眉重复。 如果 OCR 失败或未返回文本，则保留任何嵌入文本并返回警告。 仍然没有文本的页面会出现在 pages_without_text 中。

构建时会捆绑英语和德语语言模型。提取无需网络连接、下载模型或可写的模型缓存。仅在需要时启动 OCR 工作进程，在整个文档处理期间重复使用，并在完成后终止。 OCR 输入的渲染比例最高为 PDF 比例的 2.5 倍，每页最多 800 万像素。 OCR 识别（包括引擎启动，但不包括 PDF 渲染）每页限时 60 秒。如果工作进程失败或超时，则会将其终止；剩余页面会保留嵌入文本并附带警告。

嵌入文本会根据位置分组成行和段落。较大的水平间距会用 | 表示，以提高基本表格的可读性。OCR 使用 Tesseract 的段落检测和词语位置。这些是可读性启发式规则，并非语义表格提取或复杂布局分析。多栏、旋转、手写或扫描质量较差的页面可能会出现顺序或文本错误。扫描正文上方含有大量嵌入文本的页面可能不会触发 OCR。OCR 置信度较低时会生成警告；置信度较高也不代表结果一定正确。 大小限制针对输入字节数，不限制 PDF 解压或处理时间。服务可以读取其 OS 用户有权访问的任何 PDF；没有目录沙箱。 文本会返回给 MCP 客户端，并受客户端自身的数据处理设置约束。

开发

在仓库根目录运行：

npm ci --prefix mcp
npm run build --prefix mcp
node mcp/dist/index.js

CLI 是独立的软件包，因此安装它不会安装 React。 它包含 Tesseract.js 和原生 Node canvas 依赖项。请使用 @napi-rs/canvas 支持的平台，并允许 npm 安装对应平台的二进制文件（不要省略可选依赖项）。构建时会将开发模型软件包复制到 dist/tessdata/；使用者无需安装开发依赖项。该软件包自身的锁定文件可确保构建可复现。根应用的命令保持不变。

浏览器服务和此 CLI 使用 src/shared/ 中相同的运行时无关提取核心：页面处理、嵌入文本读取、扫描检测、OCR 回退、段落、表格间距和警告。浏览器和 Node 适配器各自保留文件访问、PDF.js 设置、渲染限制和 OCR 工作进程管理。现有浏览器结果接口和此工具的 JSON 契约均保持不变。构建会清理生成的输出，并将编译后的 dist/shared/ 模块包含在 tarball 中；运行时使用者无需从仓库获取共享源文件。

使用 MCP Inspector 测试

无需克隆或构建即可测试已发布的软件包：

npx -y @modelcontextprotocol/[email protected] --cli npx -y [email protected] --method tools/list
npx -y @modelcontextprotocol/[email protected] --cli npx -y [email protected] --method tools/call --tool-name extract_pdf_text --tool-arg "file_path=/absolute/path/to/contract.pdf"

要使用浏览器版 Inspector：

npx -y @modelcontextprotocol/[email protected] npx -y [email protected]

点击 Connect，打开 Tools，然后使用本地 PDF 路径调用 extract_pdf_text。 Inspector 是开发工具，不是此软件包的运行时依赖项。

要检查本地开发构建，请在完成构建后从仓库根目录运行：

npx -y @modelcontextprotocol/[email protected] --cli node mcp/dist/index.js --method tools/list
npx -y @modelcontextprotocol/[email protected] --cli node mcp/dist/index.js --method tools/call --tool-name extract_pdf_text --tool-arg "file_path=/absolute/path/to/contract.pdf"

自动化测试与打包

npm test --prefix mcp
cd mcp
npm pack

使用 tar -tzf pdf-text-extractor-mcp-0.1.1.tgz 检查 tarball。 其中包含编译后的 JavaScript（包括 OCR 工作进程）、两个压缩的语言模型、第三方声明文件、本 README 和软件包元数据。在单独的目录中安装它，以验证无需源代码检出即可运行可执行文件：

mkdir /tmp/pdf-mcp-install
cd /tmp/pdf-mcp-install
npm install /absolute/path/to/mcp/pdf-text-extractor-mcp-0.1.1.tgz
./node_modules/.bin/pdf-text-extractor-mcp

要从仓库根目录对已安装的可执行文件运行集成测试：

MCP_TEST_CLI=/tmp/pdf-mcp-install/node_modules/.bin/pdf-text-extractor-mcp npm test --prefix mcp

发布新版本

已发布的版本无法覆盖； 请递增版本号以发布下一个版本，并更新两个 README 中固定版本的示例。 项目代码采用 MIT 许可证；软件包包含 LICENSE，版权归 Prashant Bhatia 所有，© 2026。捆绑的 OCR 模型仍采用 Apache-2.0 许可证，并在 THIRD_PARTY_NOTICES.md 和 licenses/Apache-2.0.txt 中注明归属信息。

在 mcp/ 中：

npm login --auth-type=web
npm version patch --no-git-tag-version
npm test
npm pack
npm publish --dry-run --access public
npm publish --access public --auth-type=web

发布前，请按上述说明检查并测试打包后的制品。 发布需要访问启用了 2FA 的维护者 npm 账户； 按 npm 提示完成任何浏览器授权。提交此次发布的版本、锁文件和 文档更改。构建和测试不会自动发布。请从 mcp/ 发布， 因为根目录的 React 软件包仍为私有。

发布到 MCP Registry

注册表标识符为 io.github.Prashant2204/pdf-text-extractor-mcp。 package.json 中的 mcpName 必须与 server.json 中的 name 一致。请确保 server.json 中的软件包版本、服务版本和 npm 软件包版本保持一致。 先发布 npm 软件包，以便注册表验证其元数据。

使用 brew install mcp-publisher 安装官方发布工具，然后在 mcp/ 中：

mcp-publisher validate
mcp-publisher login github
mcp-publisher publish

按提示完成 GitHub 设备授权。使用以下命令验证已发布的条目：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Prashant2204/pdf-text-extractor-mcp"

注册表列出元数据；npm 分发本地 STDIO 服务。 请参阅官方发布指南。

集成测试通过 STDIO，对生成的仅含图像的 PDF 页面、混合页眉/扫描页面、空白页面和嵌入文本页面运行真实的英语/德语 OCR。 其他测试涵盖排序、表格间隙、OCR 超时，以及图像检查或 OCR 资源失败时的部分结果。上述同一集成测试也可针对已安装的可执行文件运行。 捆绑模型的归属信息请参阅 THIRD_PARTY_NOTICES.md。

官方参考资料

• SDK 第一个服务
• SDK STDIO 传输
• MCP Inspector
• VS Code MCP 服务

实现已通过稳定版 @modelcontextprotocol/server 2.4.0 验证， 使用 McpServer.registerTool() 和 serveStdio()。浏览器和 MCP 软件包 均使用 PDF.js 6.5.438。