pdfport

pdfport

pdfport 可完成五种常见的 PDF 操作：提取文件中的文本、读取文档元数据、汇总文档信息（页数、页面尺寸、文件大小、PDF 版本）、将多个文件合并为一个，以及将文件拆分为每页一个文档。它仅处理本地文件，不会将文件上传到任何地方。

其引擎是专为本项目编写的轻量级纯 TypeScript PDF 实现。项目未捆绑任何 PDF 库，除 MCP SDK 外也没有运行时依赖。引擎会扫描文档的间接对象，沿 Catalog 找到 Pages 树，解码普通内容流和 FlateDecode 内容流，并从标准文本显示操作符中提取文本。合并时会为源对象重新编号，将其合并到一个新的对象图中，并重建页面树；拆分时也会以相同方式为每页生成一个文档。两者都会写入重新计算的交叉引用表。

范围 — 引擎的支持与不支持

支持：页面树为扁平结构的简单 PDF（Catalog 的 Pages 节点直接列出 Page 对象——这是常见生成器生成的结构，也是 pdfport 自身合并和拆分时写入的结构）、未压缩或 FlateDecode 内容流、内容流和 Info 字典中的字面字符串及十六进制字符串，以及每页的 MediaBox 尺寸（页面未指定时从 Pages 节点继承）。

不支持：加密文件、对象流和压缩交叉引用流（PDF 1.5+ 紧凑文件）、嵌套页面树、需要 ToUnicode 映射才能读取的嵌入字体编码，以及合并或拆分时保留表单/注释。对于不在支持范围内的文件，程序会报出明确说明缺少内容的错误——pdfport 绝不会返回虚构的文本或元数据。

安装

npx @reneturcios/pdfport get-pdf-info ./report.pdf

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/pdfport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Print the document's text
pdfport extract-text ./report.pdf

# Print the Info-dictionary metadata (plus page count) as JSON
pdfport get-metadata ./report.pdf

# Print page count, page sizes, file size and PDF version as JSON
pdfport get-pdf-info ./report.pdf

# Merge inputs, in order, into one output file
pdfport merge ./combined.pdf ./a.pdf ./b.pdf ./c.pdf

# Split into <name>-page-1.pdf, <name>-page-2.pdf, ... in a directory
pdfport split ./report.pdf ./report-pages

# Start the MCP server
pdfport mcp

pdfport --version

退出代码：成功时为 0；文件缺失或无法处理文档时为 1（错误信息会说明原因）；用法错误时为 2。

MCP 服务

同一个可执行文件支持两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/pdfport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "pdfport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pdfport", "mcp"]
    }
  }
}

工具

工具	输入	返回内容
extract_text	file_path（字符串，必填）	文件文本：每页显示的文本，各页之间以换行符连接。
get_metadata	file_path（字符串，必填）	Info 字典中的标题、作者、主题、关键词、创建者、制作者和日期（仅包含文档中存在的字段），以及页数。
get_pdf_info	file_path（字符串，必填）	页数、每页以点为单位的 MediaBox 尺寸、文件大小（字节）以及文件头中的 PDF 版本。
merge_pdfs	input_files（字符串数组，必填），output_file（字符串，必填）	写入合并后的文档，并返回输出路径和总页数。保留第一个输入文件的元数据。
split_pdf	file_path（字符串，必填），output_dir（字符串，必填）	在指定目录中为每页写入一个单页文件，并返回创建的文件路径和页数。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

测试套件会从原始字符串构建小型 PDF，涵盖普通内容流和 FlateDecode 内容流，并端到端测试默认引擎：文本提取（包括 TJ 数组和字面字符串转义）、元数据、文档信息、合并和拆分都会针对真实实现进行断言；随后还会使用临时目录中的真实文件测试文件接口。

许可证

MIT — 参见 LICENSE。