FastMCP 技能库 PDF 处理实战基于 pypdf 的文本提取、表单填写与文档合并【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本文是 FastMCP 技能示例体系中pdf-processing技能的配套参考文档解读核心围绕 Python 生态中成熟的 pypdf 库给出 PDF 文本提取、表单填写、多文档合并三组可直接复用的代码范式。读者学完后既能掌握 pypdf 的核心 API 用法也能理解这些代码在 FastMCP skills 架构中如何被组织为技能资源skill://pdf-processing/reference.md并通过 MCP 客户端被发现、读取与下载为构建文档处理类 Agent 技能提供完整落地路径。一、reference.md 在 FastMCP 技能体系中的定位在 FastMCP 的 skills 示例中每个技能目录遵循固定的组织结构。以本仓库的 pdf-processing 技能目录 为例sample_skills/ └── pdf-processing/ ├── SKILL.md # 技能主文件含 description/version/tags 前置元数据 └── reference.md # 支撑文档详细的 API 参考即本文依据的原始文档其中 SKILL.md 通过 YAML frontmatter 声明技能的能力元数据--- description: Extract text from PDFs, fill forms, and merge documents version: 1.0.0 tags: [document, pdf, extraction] ---它概述了技能的四大能力——提取 PDF 文本内容、填充 PDF 表单字段、合并多个 PDF、按页拆分 PDF并显式指向reference.md作为详细 API 文档。也就是说本文所解读的reference.md承担的是技能底层的可执行代码范式角色SKILL.md 告诉 Agent何时用reference.md 告诉 Agent怎么用。从源码实现看SkillProvider 在加载技能时解析 frontmatter 生成技能描述并扫描目录内全部文件构建文件清单支撑文件如reference.md默认通过skill://{name}/{path*}资源模板暴露客户端可随时按需读取。二、文本提取pypdf 基础用法reference.md首先给出的是最常用的 PDF 文本提取代码from pypdf import PdfReader reader PdfReader(document.pdf) for page in reader.pages: text page.extract_text() print(text)要点拆解PdfReader(document.pdf)打开 PDF 文件可传入文件路径或文件对象。读取的是 PDF 页面的文本层内容。reader.pages返回页面对象序列可迭代或按下标访问如reader.pages[0]取第一页。page.extract_text()提取该页的全部可见文本。需要说明的适用前提extract_text()依赖 PDF 内嵌的真实文本层扫描件、纯图片型 PDF 无文本层可提取需配合 OCR 方案不在 pypdf 范围内。在实际技能调用中Agent 往往需要先解析 PDF 目录结构再决定是否采用本方法。三、表单填写基于 form fields APIreference.md给出了 PDF 表单AcroForm填充的标准做法from pypdf import PdfReader, PdfWriter reader PdfReader(form.pdf) writer PdfWriter() writer.append(reader) writer.update_page_form_field_values( writer.pages[0], {field_name: field_value} ) with open(filled_form.pdf, wb) as output: writer.write(output)关键 API 说明writer.append(reader)把原 PDF含表单结构整体追加进写入器避免逐页手动拷贝丢失表单定义。writer.update_page_form_field_values(page, field_values_dict)以{字段名: 字段值}字典批量填充指定页的表单字段。字段名可通过reader.get_fields()预先枚举获得pypdf 通用能力可在实际技能脚本中先打印字段清单再填充。writer.write(output)将填充结果写出为新文件原始form.pdf保持不变符合读取-填充-另存的安全操作惯例。这套写法特别适合合同模板、申请表批量填单类技能Agent 先探测表单字段结构再根据用户提供的键值对完成填充。四、合并 PDF多文档拼接reference.md提供的合并示例极为精简但可直接运行from pypdf import PdfWriter writer PdfWriter() writer.append(doc1.pdf) writer.append(doc2.pdf) with open(merged.pdf, wb) as output: writer.write(output)用法说明writer.append(doc1.pdf)接收文件路径或 reader 对象、页面列表按调用顺序依次并入因此合并顺序即 append 的调用顺序——在技能实现中若需调整页序可结合reader.pages切片按需 append。写出方式与表单填充一致统一通过writer.write()落盘。该模式可自然扩展为拆分场景SKILL.md 声明的另一项能力用PdfReader读取后按页切片用PdfWriter逐页写出为独立文件。五、在 FastMCP 中运行把 reference.md 变为可发现的技能资源上述代码本身不依赖 FastMCP但reference.md之所以存在于本仓库正是为了被 FastMCP skills provider 以资源形式暴露给 MCP 客户端。完整的运行链路如下。1. 启动技能服务器examples/skills/server.py 演示了三种挂载方式其中默认启用的目录扫描模式直接加载sample_skillsfrom pathlib import Path from fastmcp import FastMCP from fastmcp.server.providers.skills import ( SkillsDirectoryProvider, ) mcp FastMCP(Skills Server) skills_dir Path(__file__).parent / sample_skills mcp.add_provider(SkillsDirectoryProvider(rootsskills_dir, reloadTrue)) if __name__ __main__: mcp.run()启动命令仓库根目录下uv run python examples/skills/server.py2. 客户端发现与读取技能资源examples/skills/client.py 展示了客户端视角的完整调用链# 列出资源与模板 resources await client.list_resources() templates await client.list_resource_templates() # 读取主文件 result await client.read_resource(skill://pdf-processing/SKILL.md) # 读取清单manifest result await client.read_resource(skill://pdf-processing/_manifest) # 读取支撑文档即本文依据的 reference.md result await client.read_resource(skill://pdf-processing/reference.md) print(result[0].text[:500] ...\n)从中可以看到reference.md在运行时的资源 URI 为skill://pdf-processing/reference.md通过 SkillFileTemplate 的skill://{name}/{path*}模板解析读取时以 UTF-8 文本形式返回。3. 渐进式披露与整包下载reference.md默认属于支撑文件按 SkillProvider 的设计支撑文件默认通过 ResourceTemplate 暴露、不出现在list_resources()结果中从而降低发现成本若希望完整枚举可设置supporting_filesresourcesSkillsDirectoryProvider(rootsskills_dir, supporting_filesresources)同时每个技能都附带合成清单skill://pdf-processing/_manifest其 JSON 结构依据 manifest 生成逻辑形如{ skill: pdf-processing, files: [ {path: SKILL.md, size: 1234, hash: sha256:abc...}, {path: reference.md, size: 5678, hash: sha256:def...} ] }基于此examples/skills/download_skills.py 演示了客户端通过list_skills(client)发现技能、再通过sync_skills(client, tmp)将整个技能目录含 reference.md批量同步到本地便于离线复用。4. 读取安全边界从源码结构看SkillFileTemplate 与SkillFileResource在读取任意支撑文件前均会调用safe_join()做路径校验拒绝目录穿越、绝对路径注入、空字节与符号链接逃逸防止恶意 URI如skill://pdf-processing/../../etc/passwd越权读取文件系统。因此虽然 reference.md 中的 pypdf 代码面向本地文件操作但在 FastMCP 技能服务中所有资源读取都被限制在技能目录边界之内。六、总结reference.md用三段最小可运行代码覆盖了 PDF 处理技能最核心的三类操作文本提取PdfReader.pagesextract_text()、表单填充PdfWriter.appendupdate_page_form_field_values、文档合并PdfWriter.append顺序拼接。在 FastMCP 的 skills 架构中它作为pdf-processing技能的支撑参考文档与 SKILL.md 一起被SkillsDirectoryProvider扫描暴露最终以skill://pdf-processing/reference.md资源的形式供任意 MCP 客户端发现、读取乃至整包下载从而让 PDF 处理能力真正成为 Agent 可编程调用的技能资产。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastMCP 技能库 PDF 处理实战：基于 pypdf 的文本提取、表单填写与文档合并
FastMCP 技能库 PDF 处理实战基于 pypdf 的文本提取、表单填写与文档合并【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本文是 FastMCP 技能示例体系中pdf-processing技能的配套参考文档解读核心围绕 Python 生态中成熟的 pypdf 库给出 PDF 文本提取、表单填写、多文档合并三组可直接复用的代码范式。读者学完后既能掌握 pypdf 的核心 API 用法也能理解这些代码在 FastMCP skills 架构中如何被组织为技能资源skill://pdf-processing/reference.md并通过 MCP 客户端被发现、读取与下载为构建文档处理类 Agent 技能提供完整落地路径。一、reference.md 在 FastMCP 技能体系中的定位在 FastMCP 的 skills 示例中每个技能目录遵循固定的组织结构。以本仓库的 pdf-processing 技能目录 为例sample_skills/ └── pdf-processing/ ├── SKILL.md # 技能主文件含 description/version/tags 前置元数据 └── reference.md # 支撑文档详细的 API 参考即本文依据的原始文档其中 SKILL.md 通过 YAML frontmatter 声明技能的能力元数据--- description: Extract text from PDFs, fill forms, and merge documents version: 1.0.0 tags: [document, pdf, extraction] ---它概述了技能的四大能力——提取 PDF 文本内容、填充 PDF 表单字段、合并多个 PDF、按页拆分 PDF并显式指向reference.md作为详细 API 文档。也就是说本文所解读的reference.md承担的是技能底层的可执行代码范式角色SKILL.md 告诉 Agent何时用reference.md 告诉 Agent怎么用。从源码实现看SkillProvider 在加载技能时解析 frontmatter 生成技能描述并扫描目录内全部文件构建文件清单支撑文件如reference.md默认通过skill://{name}/{path*}资源模板暴露客户端可随时按需读取。二、文本提取pypdf 基础用法reference.md首先给出的是最常用的 PDF 文本提取代码from pypdf import PdfReader reader PdfReader(document.pdf) for page in reader.pages: text page.extract_text() print(text)要点拆解PdfReader(document.pdf)打开 PDF 文件可传入文件路径或文件对象。读取的是 PDF 页面的文本层内容。reader.pages返回页面对象序列可迭代或按下标访问如reader.pages[0]取第一页。page.extract_text()提取该页的全部可见文本。需要说明的适用前提extract_text()依赖 PDF 内嵌的真实文本层扫描件、纯图片型 PDF 无文本层可提取需配合 OCR 方案不在 pypdf 范围内。在实际技能调用中Agent 往往需要先解析 PDF 目录结构再决定是否采用本方法。三、表单填写基于 form fields APIreference.md给出了 PDF 表单AcroForm填充的标准做法from pypdf import PdfReader, PdfWriter reader PdfReader(form.pdf) writer PdfWriter() writer.append(reader) writer.update_page_form_field_values( writer.pages[0], {field_name: field_value} ) with open(filled_form.pdf, wb) as output: writer.write(output)关键 API 说明writer.append(reader)把原 PDF含表单结构整体追加进写入器避免逐页手动拷贝丢失表单定义。writer.update_page_form_field_values(page, field_values_dict)以{字段名: 字段值}字典批量填充指定页的表单字段。字段名可通过reader.get_fields()预先枚举获得pypdf 通用能力可在实际技能脚本中先打印字段清单再填充。writer.write(output)将填充结果写出为新文件原始form.pdf保持不变符合读取-填充-另存的安全操作惯例。这套写法特别适合合同模板、申请表批量填单类技能Agent 先探测表单字段结构再根据用户提供的键值对完成填充。四、合并 PDF多文档拼接reference.md提供的合并示例极为精简但可直接运行from pypdf import PdfWriter writer PdfWriter() writer.append(doc1.pdf) writer.append(doc2.pdf) with open(merged.pdf, wb) as output: writer.write(output)用法说明writer.append(doc1.pdf)接收文件路径或 reader 对象、页面列表按调用顺序依次并入因此合并顺序即 append 的调用顺序——在技能实现中若需调整页序可结合reader.pages切片按需 append。写出方式与表单填充一致统一通过writer.write()落盘。该模式可自然扩展为拆分场景SKILL.md 声明的另一项能力用PdfReader读取后按页切片用PdfWriter逐页写出为独立文件。五、在 FastMCP 中运行把 reference.md 变为可发现的技能资源上述代码本身不依赖 FastMCP但reference.md之所以存在于本仓库正是为了被 FastMCP skills provider 以资源形式暴露给 MCP 客户端。完整的运行链路如下。1. 启动技能服务器examples/skills/server.py 演示了三种挂载方式其中默认启用的目录扫描模式直接加载sample_skillsfrom pathlib import Path from fastmcp import FastMCP from fastmcp.server.providers.skills import ( SkillsDirectoryProvider, ) mcp FastMCP(Skills Server) skills_dir Path(__file__).parent / sample_skills mcp.add_provider(SkillsDirectoryProvider(rootsskills_dir, reloadTrue)) if __name__ __main__: mcp.run()启动命令仓库根目录下uv run python examples/skills/server.py2. 客户端发现与读取技能资源examples/skills/client.py 展示了客户端视角的完整调用链# 列出资源与模板 resources await client.list_resources() templates await client.list_resource_templates() # 读取主文件 result await client.read_resource(skill://pdf-processing/SKILL.md) # 读取清单manifest result await client.read_resource(skill://pdf-processing/_manifest) # 读取支撑文档即本文依据的 reference.md result await client.read_resource(skill://pdf-processing/reference.md) print(result[0].text[:500] ...\n)从中可以看到reference.md在运行时的资源 URI 为skill://pdf-processing/reference.md通过 SkillFileTemplate 的skill://{name}/{path*}模板解析读取时以 UTF-8 文本形式返回。3. 渐进式披露与整包下载reference.md默认属于支撑文件按 SkillProvider 的设计支撑文件默认通过 ResourceTemplate 暴露、不出现在list_resources()结果中从而降低发现成本若希望完整枚举可设置supporting_filesresourcesSkillsDirectoryProvider(rootsskills_dir, supporting_filesresources)同时每个技能都附带合成清单skill://pdf-processing/_manifest其 JSON 结构依据 manifest 生成逻辑形如{ skill: pdf-processing, files: [ {path: SKILL.md, size: 1234, hash: sha256:abc...}, {path: reference.md, size: 5678, hash: sha256:def...} ] }基于此examples/skills/download_skills.py 演示了客户端通过list_skills(client)发现技能、再通过sync_skills(client, tmp)将整个技能目录含 reference.md批量同步到本地便于离线复用。4. 读取安全边界从源码结构看SkillFileTemplate 与SkillFileResource在读取任意支撑文件前均会调用safe_join()做路径校验拒绝目录穿越、绝对路径注入、空字节与符号链接逃逸防止恶意 URI如skill://pdf-processing/../../etc/passwd越权读取文件系统。因此虽然 reference.md 中的 pypdf 代码面向本地文件操作但在 FastMCP 技能服务中所有资源读取都被限制在技能目录边界之内。六、总结reference.md用三段最小可运行代码覆盖了 PDF 处理技能最核心的三类操作文本提取PdfReader.pagesextract_text()、表单填充PdfWriter.appendupdate_page_form_field_values、文档合并PdfWriter.append顺序拼接。在 FastMCP 的 skills 架构中它作为pdf-processing技能的支撑参考文档与 SKILL.md 一起被SkillsDirectoryProvider扫描暴露最终以skill://pdf-processing/reference.md资源的形式供任意 MCP 客户端发现、读取乃至整包下载从而让 PDF 处理能力真正成为 Agent 可编程调用的技能资产。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考