MCP 实战：为 PDF 工具集构建 Agent 接口

我是 PDFHaul 的独立创始人。PDFHaul 是一款免费的浏览器端和移动端 PDF 工具。几个月前，我反复遇到同一个麻烦：每当我想让 AI Assistant 帮忙处理 PDF 任务时，都必须手动下载文件、上传到某个地方、运行工具，然后再把处理结果放回对话中。只要涉及多个文件，这套流程很快就会让人不胜其烦。

于是，我为 PDFHaul 构建了一个 MCP Server。本文将介绍它能做什么、如何实现，以及开发过程中几个比较棘手的决策。

MCP 在这里真正解决了什么问题

Model Context Protocol 为 AI Assistant 提供了一种直接调用外部工具的标准方式，不再需要由人充当 Assistant 与各项服务之间的手动桥梁。具体到 PDF 处理，这意味着 Claude 或 Cursor 之类的 Assistant 可以在对话过程中直接合并、拆分、压缩或转换文件，而不需要用户离开对话，单独运行工具。

PDFHaul MCP Server 对外提供了 12 个工具，分为四类：文件管理、编辑、格式转换和压缩。服务已经在 pdfhaul.com/mcp-server 上线，你可以在那里找到配置说明并生成 API key。

这套 Server 与 PDFHaul 的其他部分共用 Node.js/TypeScript 技术栈和 GCP Cloud Run 基础设施，因此初期开发比从零搭建一套独立服务简单得多。这些工具本质上是对现有 PDF 处理逻辑的封装，所以我并不需要重新实现 PDF 处理能力，只需通过一个新的接口将它们暴露出来。

有几个决策花费的思考时间比我预想的更多：

身份验证。 API key 在存储前会使用 bcrypt 进行哈希处理，请求则通过 API key 与 JWT 的组合完成身份验证。即使这是一款免费产品，我也不想存储任何类似明文凭证的数据，因为 API key 经常会被粘贴进配置文件，然后意外提交到代码仓库——这种事情发生的频率，可能比任何人愿意承认的都高。

速率限制。 系统按照每个 key 在内存中进行速率限制，初始参数设置得相对保守。Cloud Run 的无状态特性意味着，实例冷启动时，内存中的限制状态会被重置。如果你正在构建类似的产品，这是一个需要了解的现实取舍。对于 v1 版本，我暂时接受了这一点，而没有为此专门部署 Redis。

SSRF 防护。 有几个工具接受 URL 作为输入。例如，用户可以提供一个 PDF 的地址，让 Server 获取并处理它，而不必直接上传文件字节。任何接受调用方所提供 URL 的工具，都可能成为服务端请求伪造攻击的入口。因此，在 Server 真正发起获取请求之前，会先根据内部 IP 地址段黑名单以及非 HTTP(S) 协议规则，对请求进行校验。

幂等键。 AI Assistant 有时会重试工具调用，原因可能是请求超时、连接中断，也可能只是 Assistant 自己决定再尝试一次。如果没有幂等处理，重试一次“合并这些文件”的调用，可能会生成重复结果，或者重复占用速率限制额度。每一次会改变状态的工具调用都接受一个 idempotency key，这样在发生重试时，就会返回最初的结果，而不是再次执行相同的处理。

审计日志。 每一次工具调用都会被记录，日志中包含足以还原事件经过的信息，但不会记录文件内容本身。对于 PDF 工具来说，这一点可能比其他 API 更重要，因为整个产品的信任模型都建立在一个原则之上：用户文件的保留时间不会超过必要期限。

这套 Server 已经收录进官方 MCP registry，而它目前也是主要的用户发现渠道。与在其他生态中开发 plugin 或等待 marketplace 审核相比，registry 的收录流程轻量得令人耳目一新。

接下来会怎样

在我见过的 PDF 厂商中，Foxit 和 Nitro 也在构建 MCP Server。这两家公司规模更大，并且已经拥有成熟的企业级 PDF 产品。作为一名独立创始人，尽早进入这个领域，并不是为了与它们正面竞争，而是希望在市场变得拥挤之前，真正为使用 AI Assistant 工具的人群提供价值。

如果你正在 AI Assistant 工作流中处理 PDF，并且想试试看，这套 Server 可以免费使用：pdfhaul.com/mcp-server。如果你对实现细节有任何疑问，欢迎在评论区提问。尤其是身份验证或 SSRF 防护方面，如果你也在开发类似的产品，我很乐意交流。

Peter，PDFHaul 创始人

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。