在 Goose 中接入 PDF Reader MCP 扩展：让 Agent 直接阅读并抽取 PDF 文档内容

在 Goose 中接入 PDF Reader MCP 扩展让 Agent 直接阅读并抽取 PDF 文档内容【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goosePDF尤其是带密码保护、版面复杂、页数众多的文档历来是 LLM Agent 获取本地信息时的难点。本文以当前仓库 Goose 官方扩展文档documentation/docs/mcp/pdf-mcp.md为主线完整讲解如何把PDF Reader MCP ServerPyPI 包名mcp-read-pdf注册为 Goose 的一个扩展涵盖 goose Desktop 一键安装、goose configure命令行交互配置、扩展配置在底层的持久化方式并用一份简历评估的真实示例演示最终效果。读完本文你将掌握在 Goose 中挂载任意基于uvx发布的本地 MCP 扩展的标准流程并能让 Goose 直接读取本地 PDF 文件中的文字内容。为什么 Goose 需要 PDF Reader 这类 MCP 扩展Goose 是一个可执行、可编辑、可测试的开放源码 AI Agent但它本身并不知道如何把二进制 PDF 中的文字读出来——这正是 MCPModel Context Protocol扩展发挥作用的地方。把 PDF Reader MCP Server 添加为 Goose 的扩展后Goose 的能力边界从读文本文件扩展到读取受保护加密与不受保护的 PDF 文档并抽取其中的文本读取大型、复杂排版的 PDF 文档既支持只读指定页也支持读取整份文档。该扩展会向 Goose 暴露read_pdf工具。从本文下方示例的会话输出可以看到Goose 会以类似─── read_pdf | pdf ─────的形式调用它并传入file_path参数——PDF Reader 运行期就是一个标准的 MCP Server 进程通过 stdio 与 Goose 通信。前置条件先装好 uv因为该扩展是通过uvx运行的这是 Astral 提供的uv工具链中运行 Python 包的命令所以在开始前需要确认系统已安装uv。这是运行uvx mcp-read-pdf命令的前提安装方式可参考 uv 官方安装说明属于外部工具本身的前提与本仓库无关。验证是否就绪uvx --help能正常打印帮助信息即说明环境可用。快速安装两条路径任选其一PDF Reader 扩展的官方推荐安装方式分两种取决于你使用的是 goose Desktop 还是 goose CLI。方式一goose Desktop —— 通过 goose:// 深链一键安装goose Desktop 支持一键安装扩展页面中提供的安装器本质是构造一条goose://extension?...的深链点击后由 Desktop 客户端接管并完成注册。本扩展对应的深链为goose://extension?cmduvxargmcp-read-pdfidpdf_readnamePDF%20ReaderdescriptionRead%20large%20and%20complex%20PDF%20documents该 URL 携带的参数即最终写入配置的字段逐项拆解如下URL 参数值含义cmduvx启动扩展时执行的命令argmcp-read-pdf传给命令的参数即要运行的 Python MCP 包idpdf_read扩展在配置中的唯一标识 keynamePDF Reader扩展显示名称descriptionRead large and complex PDF documents扩展描述供 Agent 理解何时调用点击该链接后安装流程依次为确认安装点击Yes→ 由于本扩展无需 API Key 或环境变量可直接Add Extension→ 点击左上角侧边栏按钮打开面板 → 进入对应会话开始使用。从 Goose 文档站的源码看这类一键安装深链是由 documentation/src/components/GooseDesktopInstaller.tsx 统一生成的组件会根据commandargsstdio 类型或urlhttp 类型拼出goose://extension链接并追加id、name、description需要密钥的扩展还会追加env或header参数。也就是说任何遵循本地命令 参数模式的 MCP Server都可以照此模板制作同款一键安装入口。方式二goose CLI —— 直接执行 uvx 命令使用 goose CLI 时快速安装等价于在会话中让 Goose 以该命令启动扩展uvx mcp-read-pdf这条命令本身即可作为扩展的启动命令注册时将其填入命令一栏即可见下文交互式配置。使用 goose configure 交互式添加扩展对于 CLI 用户文档推荐通过goose configure向导式注册扩展。整个过程对应的交互界面由 documentation/src/components/CLIExtensionInstructions.tsx 定义关键步骤拆解如下第 1 步运行配置命令goose configure第 2 步在What would you like to configure?中选择Add Extension然后在扩展类型中选择Command-line Extension因为mcp-read-pdf是一个本地 stdio 进程而非远程 HTTP 端点◆ What type of extension would you like to add? │ ○ Built-in Extension │ ● Command-line Extension (Run a local command or script) │ ○ Remote Extension (Streamable HTTP)第 3 步为扩展命名◆ What would you like to call this extension? │ PDF Reader第 4 步填写启动命令◆ What command should be run? │ uvx mcp-read-pdf第 5 步设置工具执行超时时间单位秒默认值为300◆ Please set the timeout for this tool (in secs): │ 300第 6 步填写描述该描述会被 Agent 用于判断何时调用此扩展建议语义清晰◆ Enter a description for this extension: │ Read large and complex PDF documents第 7 步本扩展无需环境变量因此在 Would you like to add environment variables? 处选择No向导会以Added PDF Reader extension结束。扩展被保存到哪里底层配置与源码佐证无论是 Desktop 深链一键安装还是 CLI 向导最终都会写入 Goose 的同一份全局配置文件中的extensions节点。以向导交互生成的配置为例等价于如下 YAML 结构extensions: pdf_read: enabled: true type: stdio name: PDF Reader cmd: uvx args: - mcp-read-pdf timeout: 300 description: Read large and complex PDF documents这些规则并非黑盒而是有仓库源码直接支撑的配置的读写逻辑位于 crates/goose/src/config/extensions.rs。每个扩展被建模为ExtensionEntry { enabled, config: ExtensionConfig }其中ExtensionConfig::Stdio携带name、cmd、args、envs、timeout、cwd、description等字段正好对应上面 YAML 中的每一项。扩展 key 并非随意指定源码中的name_to_key()会把扩展名中的空白字符去掉、其他非法字符替换为_并转为小写因此PDF Reader对应的配置 key 是pdf_read而非pdf_reader且提供inject_name_if_missing在 YAML 未显式声明name时自动用 map key 兜底填充。DEFAULT_EXTENSION_TIMEOUT: u64 300常量与上面第 5 步的默认超时300秒一一对应超过该时长仍未返回的调用会被视为超时。该文件内的单元测试如test_stdio_without_name_uses_map_key、test_set_extension_enabled_preserves_clean_siblings直接以type: stdiocmdargs的 YAML 片段验证解析逻辑可据此确认手工书写配置时的字段写法与兜底行为。一个值得注意的细节is_extension_available()会过滤掉在当前版本 Goose 中不存在的平台扩展但Stdio类型的本地命令扩展不受限制——因此 PDF Reader 这类由uvx拉起的第三方 MCP Server 可以无障碍注册同时配置解析对解析失败的畸形条目会跳过并记录日志而不是让整个配置文件失效。实战示例用 Goose 自动评估简历配置完成后即可在会话中直接使用。文档给了一个有代表性的场景读取求职者简历并按岗位要求打分。向 Goose 发送如下提示词Read the resume at ~/Downloads/resume.pdf and evaluate how well this candidate aligns with the following role requirements: - 5 years of backend development experience - Strong system design and distributed systems knowledge - Cloud infrastructure experience (AWS preferred) - Prior experience leading technical projects or teams - Bonus: familiarity with LLMs or AI/ML tools Give a score out of 5 for each requirement, supporting evidence, and a summary at the end with pros, cons, and a decision: Strong Fit / Moderate Fit / Weak Fit.Goose 会先调用扩展暴露的read_pdf工具读取 PDFIll help analyze the resume against those requirements. Let me read the PDF first. ─── read_pdf | pdf ────────────────── file_path: ~/Downloads/resume.pdf随后基于抽取出的正文逐条打分并输出结构化结论。从文档示例看其输出格式为每个维度给出Score: x/5与支撑证据工作年限、技术栈、AWS 服务清单、带团队经历、ML/NLP 接触情况最后汇总Pros / Cons / Decision与总分。示例中简历总体得分为 21.5/25不含加分项判定为Strong Fit。这个例子清晰地展示了扩展的典型工作流提示词指向本地 PDF → Goose 判断需要使用 read_pdf 工具 → 工具返回文本 → Agent 基于文本完成推理。得益于扩展机制整个过程中 PDF 的二进制解析细节对 Agent 完全透明~/Downloads/resume.pdf这类本机路径也可以直接作为file_path传入。扩展实践小结把 PDF Reader 挂到 Goose 上本质上是把任意uvx可运行的 MCP Server 接入 Goose 扩展体系的通用范例可归纳为一条可复用方法论准备运行环境确认uv/uvx可用这是大多数基于 Python 分发的 MCP Server 的共同前提选择注册方式goose Desktop 使用goose://extension?cmd...arg...id...name...description...深链一键安装CLI 使用goose configure选择Command-line Extension按向导填写名称、命令uvx mcp-read-pdf、超时默认 300 秒与描述理解落盘配置注册结果保存在配置文件的extensions.key节点key 由扩展名经 name_to_key 规范化而来字段结构以ExtensionEntry/ExtensionConfig::Stdio为准解析逻辑均有单元测试覆盖验证与使用在会话中给 Goose 一个指向本地 PDF 的任务观察其是否按需调用read_pdf并对返回文本进行后续推理。对于经常需要让 Agent 处理合同、简历、论文、报表等本地 PDF 资料的场景这一扩展是让 Goose 从只能看纯文本升级为能读懂 PDF的最轻量路径。若想进一步了解 Goose 扩展机制的其余类型内置扩展、远程 Streamable HTTP 扩展与更多可接入的 MCP 服务可继续浏览 documentation/docs/mcp 目录下的其他扩展指南。【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考