pdf-toolkit-mcp

免责声明。 pdf-toolkit-mcp 是一个独立的社区开源客户端。它与 iLovePDF SL 无关联，也未获其认可、赞助或认证。本项目使用你自己的项目凭据，连接公共 iLoveAPI REST 服务；不会代理、转售或重新授权任何内容。“iLovePDF”和“iLoveAPI”是 iLovePDF SL 的商标；本项目不主张拥有这些商标。

📖 目录

• 为什么选择 pdf-toolkit-mcp
• 快速浏览
• 安装
• 工具目录
• 工作流方案
• 架构
• 配置参考
• 安全模型
• 开发
• 测试与 CI
• 发布
• 路线图
• 常见问题
• 参与贡献
• 许可证与商标
• 鸣谢

🎯 为什么选择 pdf-toolkit-mcp

个人使用免费。 iLoveAPI 的免费套餐每月提供约 2,500 点数；此 MCP 使用 MIT 许可证，完全免费。

🚀 快速浏览

安装后，只需告诉 Claude 你要做什么。模型会判断该调用哪些工具：

You: Merge invoice-jan.pdf and invoice-feb.pdf into Q1.pdf, then compress it hard
     and lock it with the password "2026q1".

Claude (planning):
  1. merge_pdf     → invoice-jan.pdf + invoice-feb.pdf  →  Q1.pdf
  2. compress_pdf  → Q1.pdf                             →  Q1-compressed.pdf  (level: extreme)
  3. protect_pdf   → Q1-compressed.pdf                  →  Q1-compressed-protected.pdf

Claude (result):
  ✅ Created ~/docs/Q1-compressed-protected.pdf (312 KB, password-protected).

📦 安装

前置条件

• Node.js ≥ 18（推荐使用 LTS 版本）。
• iLoveAPI 项目密钥 — 可在 developer.ilovepdf.com 免费注册。约需 2 分钟：
  1. 注册 → 创建项目 → 复制 Project public key 和 Project secret key。
  2. 导出密钥（或将它们填入客户端的 MCP 配置中 — 示例见下文）。

选项 A — Claude Code（CLI 一行命令安装）

export ILOVEAPI_PROJECT_PUBLIC_KEY="project_public_xxx"
export ILOVEAPI_PROJECT_SECRET_KEY="secret_key_xxx"

claude mcp add pdf-toolkit -- npx -y pdf-toolkit-mcp

重启 Claude Code 后，选择器中就会显示全部 18 个工具。使用 /mcp 验证 → 你应该会看到 pdf-toolkit: connected (18 tools)。

选项 B — Claude Code 插件（包含 pdf-workflow skill）

/plugin marketplace add EigenCharlie/pdf-toolkit-mcp
/plugin install pdf-toolkit@EigenCharlie/pdf-toolkit-mcp

该插件会自动配置 MCP 服务，并且安装一个 skill，教 Claude 掌握五种经典的多步骤 PDF 工作流（参见工作流示例）。

选项 C — Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "pdf-toolkit-mcp"],
      "env": {
        "ILOVEAPI_PROJECT_PUBLIC_KEY": "project_public_xxx",
        "ILOVEAPI_PROJECT_SECRET_KEY": "secret_key_xxx"
      }
    }
  }
}

选项 D — 通过 stdio 使用任意 MCP 客户端

ILOVEAPI_PROJECT_PUBLIC_KEY=… ILOVEAPI_PROJECT_SECRET_KEY=… npx -y pdf-toolkit-mcp

该服务通过 stdio 使用标准 MCP JSON-RPC 2.0 帧格式。可将它接入 Cursor、Windsurf、mcphub、mcp-inspector，或任何支持 MCP 的工具。

选项 E — Claude Desktop .mcpb 捆绑包（拖放安装）

从最新的 GitHub Release下载 pdf-toolkit-mcp-<version>.mcpb，然后将其拖入 Claude Desktop → Settings → Extensions。Claude 会通过捆绑清单的 user_config 部分提示你输入 iLoveAPI 密钥。无需 npx、Node 或终端。

捆绑包未签名（尚无发布者证书）。macOS Gatekeeper / Windows SmartScreen 首次安装时可能会发出警告；接受前请核对发布说明中的 SHA-256。

选项 F — MCP Registry（兼容客户端自动发现）

该服务已在官方 MCP Registry 中编入索引，条目为 io.github.EigenCharlie/pdf-toolkit-mcp。可浏览 Registry 的客户端（Claude Desktop 扩展面板、VS Code MCP 选择器、mcphub 等）无需手动配置即可安装 — 它们会指向 npm 包，并自动提示你设置两个 iLoveAPI 环境变量。

🧰 工具目录

全部 18 个工具均使用严格的 Zod schema、additionalProperties: false，并同时返回 text 摘要和 file:// 资源 URI，以便客户端展示输出。

📚 整理

🔄 转换 — 从 PDF 转换

🔄 转换 — 转换为 PDF

✏️ 编辑

🔐 安全

🩹 修复 / OCR

所有工具的 input_file(s) 均支持绝对路径或相对于 CWD 的路径，并可选填 output_path（文件或目录）。默认会将结果保存到第一个输入文件所在位置，并使用带时间戳的名称。

🍳 工作流示例

捆绑的 pdf-workflow 技能（skills/pdf-workflow/SKILL.md）会教 Claude 五种经典多步骤流程。你也可以手动运行——只需描述最终状态，Claude 就会为你串联这些工具。

merge_pdf([a.pdf, b.pdf, c.pdf])
   → compress_pdf(level="recommended")
   → protect_pdf(password="…")

office_to_pdf(report.docx)
   → add_watermark(mode="text", text="CONFIDENTIAL", opacity=30)
   → protect_pdf(password="…")

extract_pdf_pages(scan.pdf, pages="3-9")
   → ocr_pdf(languages=["eng"])
   → pdf_to_word

compress_pdf(big.pdf, level="extreme")
   → protect_pdf(password="…")

repair_pdf(scan_broken.pdf)
   → ocr_pdf(languages=["eng"])
   → add_page_numbers(position="bottom-center")

🏛 架构

┌────────────────────────────┐    stdio    ┌──────────────────────────┐
│     Claude Code / Desktop  │◀───────────▶│   pdf-toolkit-mcp server │
│   (or any MCP client)      │  JSON-RPC   │   (this repo)            │
└────────────────────────────┘             └────────────┬─────────────┘
                                                        │
                                                        ▼
                                             ┌──────────────────────┐
                                             │  @ilovepdf/          │
                                             │  ilovepdf-nodejs     │
                                             │  (JWT + HTTP)        │
                                             └──────────┬───────────┘
                                                        │
                                                        ▼  HTTPS
                                             ┌──────────────────────┐
                                             │   iLoveAPI servers   │
                                             │   api.ilovepdf.com   │
                                             └──────────────────────┘

iLoveAPI 五阶段生命周期（在 src/api/tasks.ts 中编排）

  [ 10% ]   start     →  POST /v1/start/{tool}     (server assignment + task id)
  [ 40% ]   upload    →  POST /v1/upload           (one call per file, progress scales)
  [ 50% ]   process   →  POST /v1/process          (run the tool with params)
  [ 90% ]   download  →  GET  /v1/download/{task}  (bytes → Buffer)
  [100% ]   done      →  write to disk, emit file:// resource URI

对于耗时操作（OCR、大型合并），服务会在每个阶段边界发送 MCP notifications/progress，以便客户端显示实时进度条。

项目布局

pdf-toolkit-mcp/
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest
│   └── .mcp.json             # MCP server config (npx -y pdf-toolkit-mcp)
├── skills/
│   └── pdf-workflow/
│       └── SKILL.md          # 5-recipe skill for multi-step pipelines
├── src/
│   ├── index.ts              # #!/usr/bin/env node shebang
│   ├── server.ts             # MCP stdio bootstrap
│   ├── api/
│   │   ├── client.ts         # iLoveAPI client singleton (CJS interop via createRequire)
│   │   ├── tasks.ts          # 5-phase lifecycle orchestrator
│   │   ├── errors.ts         # HTTP → structured PdfToolkitError mapping
│   │   └── types.ts          # Types + error class
│   ├── tools/                # 18 tools, one file per concern
│   │   ├── _shared.ts        # Zod fragments + writeOutputAndReport helper
│   │   ├── merge.ts  split.ts  compress.ts
│   │   ├── convertFromPdf.ts convertToPdf.ts
│   │   ├── pageOps.ts  security.ts  watermark.ts
│   │   ├── repair.ts  ocr.ts
│   │   └── index.ts          # allTools[] barrel
│   └── util/
│       ├── paths.ts          # resolveInputs/resolveOutput + sandbox enforcement
│       ├── progress.ts       # Progress adapter
│       └── logger.ts         # stderr-only logger (stdio-safe)
├── tests/
│   ├── unit/                 # client, paths, errors, tools.merge (25 tests)
│   └── integration/          # smoke.test.ts — gated on iLoveAPI creds
├── scripts/
│   └── inspector.sh          # npm run inspect → MCP Inspector UI
└── .github/workflows/
    ├── ci.yml                # ubuntu+windows × node 18/20/22
    └── publish.yml           # Publishes to npm on v* tags with --provenance

⚙️ 配置参考

环境变量

结构化错误代码

每次失败都会返回带有稳定、机器可读代码的 PdfToolkitError：

🔒 安全模型

pdf-toolkit-mcp 的设计目标是在开发者机器上安全安装：

• 仅使用 Stdio。 服务不会打开网络套接字；它只会通过官方 SDK 向 api.ilovepdf.com 发起出站 HTTPS 调用。
• 不使用 console.log。 通过 stdio 传输的 JSON-RPC 会因任何意外的标准输出写入而损坏，因此所有日志行都会写入 process.stderr。
• 绝不持久化机密信息。 凭据仅在进程运行期间存于环境变量中，绝不会写入磁盘、日志文件或工具响应。
• 在本地生成 JWT。 @ilovepdf/ilovepdf-nodejs SDK 使用你的密钥自行签发 JWT——不会有任何密钥离开本机。
• 路径沙箱（可选）。 设置 ILOVEAPI_SANDBOX_ROOT，将服务限制在单个目录树内；任何解析后指向该目录树之外的路径都会在调用 API 前触发异常。
• 为每个工具设置扩展名白名单。 html_to_pdf 会拒绝 .exe；image_to_pdf 只接受常见的光栅图像格式，等等。
• 采用 MIT 许可证，便于审计。 约 2k 行 TypeScript。无混淆、无压缩、无 postinstall 脚本。

👩‍💻 开发

git clone https://github.com/EigenCharlie/pdf-toolkit-mcp.git
cd pdf-toolkit-mcp
npm install

常见任务

在 Claude Code 中调试

1. 在本地构建：npm run build。
2. 注册本地的 dist，而不是 npm：

   claude mcp remove pdf-toolkit    # if previously registered
   claude mcp add pdf-toolkit -- node "$(pwd)/dist/index.js"
   

3. 启动 Claude Code 前，在 shell 中设置 PDF_TOOLKIT_DEBUG=1，以查看详细的 stderr 输出。
4. 可通过 claude mcp logs pdf-toolkit 查看 stderr。

✅ 测试与 CI

• 单元测试 — client、paths、errors 和 tools.merge 共 25 项测试。全部使用模拟，无网络连接。运行 npm test。
• 集成冒烟测试 — tests/integration/smoke.test.ts 会创建两个最简有效 PDF，并端到端测试真实的 merge_pdf。该测试需要设置 ILOVEAPI_*_KEY 环境变量；出于安全考虑，在 PR CI 中会自动跳过。
• CI 矩阵 — .github/workflows/ci.yml 会在以下环境中运行 lint → typecheck → build → test：
  • OS：ubuntu-latest、windows-latest
  • Node：18、20、22

🚢 发布

推送标签时会自动执行发布：

npm version patch           # or minor / major
git push --follow-tags

随后，发布工作流会：

1. 重新运行 lint、typecheck、build 和测试。
2. 使用 --access public --provenance 发布到 npm（供应链证明）。
3. 创建包含自动生成说明的 GitHub Release。

所需的仓库机密：NPM_TOKEN（npm automation token）。

🗺 路线图

• v0.1 — 18 个 PDF 工具、stdio 传输、插件 + 技能、CI、发布到 npm
• v0.1.1 — 面向 Claude Desktop 的 MCPB 捆绑包（.mcpb）、市场清单、提交至 MCP Registry（mcpName）
• v0.2 — 将 Claude 插件提交至 anthropics/claude-plugins-official，发布配套的图像工具包
• v0.3 — 8 个图像工具（调整大小、转换、压缩、裁剪、旋转、添加水印、放大、移除背景）
• v0.4 — 签名工具（签名流程需要付费套餐，受环境变量标志控制）
• v1.0 — 为托管和多用户部署提供可选的 Streamable-HTTP 传输

有功能需求？提交 issue。

🙋 常见问题

这合法吗／安全吗／获得 iLovePDF 允许吗？ 是的。这是一个轻量级开源客户端，使用的是你自己的凭据——不会转售、重新授权或代理任何内容。iLoveAPI 服务条款明确允许使用用户提供的密钥的开源库（多个社区 SDK 多年来一直存在）。本项目不附带任何密钥，软件包名称中不使用“iLovePDF”／“iLoveAPI”，并附有所需的免责声明。

需要付费吗？ iLoveAPI 每月提供约 2,500 个免费额度（足以处理数千次小型操作）。更大的工作负载需要使用付费 iLoveAPI 套餐。此 MCP 本身采用 MIT 许可，永久免费。

可以离线使用吗？ 不可以。iLoveAPI 仅提供云端服务，因此每次工具调用都需要互联网连接。

可以固定到特定版本吗？ 可以：claude mcp add pdf-toolkit -- npx -y [email protected]。

可以自托管吗？ 可以。克隆仓库，运行 npm run build，然后让客户端指向 node ./dist/index.js。该服务完全无状态。

如果 iLoveAPI 宕机了会怎样？ 该工具会返回一个 PdfToolkitError，其中包含 code: "API_ERROR" 和 data.http_status。Claude 可以代表你使用指数退避策略重试。

不使用 Claude 也能用吗？ 可以——任何兼容 MCP 的客户端都能使用：Cursor、Windsurf、Zed、MCP Inspector、自定义客户端。该服务 100% 符合规范。

🤝 参与贡献

欢迎贡献！提交 PR 前，请简单检查以下事项：

1. npm run lint && npm run typecheck && npm test → 全部通过。
2. 新工具遵循 src/tools/merge.ts 中的模式（Zod 模式 → runTask → writeOutputAndReport）。
3. 至少添加一个单元测试。
4. 如果添加或重命名工具，请更新本 README 中的工具目录。

更欢迎提交 Bug 报告——请附上工具名称、参数，以及（如果可以安全分享）stderr 输出。

📜 许可证与商标

根据 MIT 许可证 发布，© 2026 Carlos。

“iLovePDF”和“iLoveAPI”是 iLovePDF SL 的商标。本项目是独立的社区构建客户端，与 iLovePDF SL 无关联，未获其认可、赞助或认证。软件包名称特意避开了这两个商标。

🙏 致谢

• iLovePDF / iLoveAPI——为每次工具调用提供支持的云端 PDF 处理 API。
• Anthropic——感谢其提供 Claude、Claude Code 和 Model Context Protocol 规范。
• @modelcontextprotocol/sdk、Zod、Vitest、ESLint——本项目所依赖的工具链。
• 感谢所有报告问题、提出工具建议和提交拉取请求的贡献者。🙌