使用 FastMCP Skills Provider 将 Agent Skills 发布为 MCP 资源架构解析与端到端实践【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本指南以 examples/skills 示例为入口讲解如何在 FastMCP 项目中把 AI 编程助手如 Claude Code的技能Skills目录通过 Provider 机制暴露为标准 MCP 资源Resources并支持客户端发现—读取—下载的完整闭环。读完本文你将掌握SkillProvider、SkillsDirectoryProvider、ClaudeSkillsProvider等核心类的用法、skill://资源寻址协议、manifest 合成机制以及配套客户端工具list_skills/sync_skills的实战调用方式。示例概览与目录结构examples/skills是一个自包含的演示目录它把一个典型 Agent Skills 生态完整搬到了 FastMCP 里服务端负责暴露技能客户端负责发现与读取工具脚本负责批量下载并附带两份示例技能文件供直接运行验证。目录结构如下examples/skills/ ├── README.md # 本文档 ├── server.py # 暴露技能的 MCP 服务器 ├── client.py # 发现并读取技能的示例客户端 ├── download_skills.py # 从服务器批量下载技能的客户端工具示例 └── sample_skills/ # 示例技能目录 ├── pdf-processing/ │ ├── SKILL.md # 技能主文件 │ └── reference.md # 辅助文档 └── code-review/ └── SKILL.md # 技能主文件其中sample_skills/pdf-processing/SKILL.md演示了带 YAML frontmatter 的技能文件包含description、version、tags字段正文用## Capabilities、## Usage描述能力并在末尾通过相对链接[reference.md](https://link.gitcode.com/i/c9c062a3129bfd0d1c3cafd365d38755)指向辅助文档code-review/SKILL.md则是一个纯指南型技能以评审清单的形式组织内容。这两份文件的形态就是 FastMCP Skills Provider 能直接消费的标准输入。快速运行示例示例提供了三种启动方式均基于仓库根目录执行启动服务器uv run python examples/skills/server.py另开终端运行发现/读取客户端uv run python examples/skills/client.py运行批量下载演示内部自建内存服务器不依赖外部进程uv run python examples/skills/download_skills.pyserver.py 创建了名为Skills Server的 FastMCP 实例并默认通过SkillsDirectoryProvider(rootsskills_dir, reloadTrue)挂载sample_skills目录client.py 则直接复用同一个 Provider 构造内存服务器再以Client(mcp)连接完整演示了列表资源 → 列表模板 → 读主文件 → 读 manifest → 读辅助文件的调用链全程无需真实网络进程。三层 Provider 架构Skills 体系采用两层抽象由 skills/init.py 统一导出Provider职责源码位置SkillProvider处理单个技能文件夹将其内文件暴露为资源skill_provider.pySkillsDirectoryProvider扫描目录为每个含主文件的子文件夹创建一个SkillProviderdirectory_provider.pyClaudeSkillsProvider面向 Claude Code 技能的便捷子类默认根目录为~/.claude/skills/claude_provider.pySkillsDirectoryProvider继承自AggregateProvider在初始化时或reloadTrue时每次请求扫描每个根目录下的子文件夹凡是存在主文件默认SKILL.md的目录就视为一个技能并生成对应SkillProvider。从源码看directory_provider.py#L76-L116扫描逻辑有几个值得注意的行为非目录、缺少主文件的子目录会被静默跳过同名技能采用先到先得去重策略——多根目录场景下更靠前的根目录拥有更高优先级单个技能加载失败FileNotFoundError/PermissionError/OSError不会拖垮整个 Provider而是记录异常后继续文件遍历使用排序后的rglob保证跨平台输出顺序稳定见 _common.py 的scan_skill_files。ClaudeSkillsProvider只是把根目录固定为Path.home() / .claude / skills其余参数原样透传给父类。每个技能暴露为三类资源对于一个名为{name}的技能Provider 会暴露以下资源形态主文件资源skill://{name}/SKILL.md——返回技能主文件的文本内容合成 manifest 资源skill://{name}/_manifest——返回 JSON 文件清单详见下文辅助文件默认通过ResourceTemplateskill://{name}/{path}提供也可配置为显式Resource列表。主文件与 manifest 由SkillResource实现skill_provider.py#L37-L69当is_manifestTrue时read()动态生成 JSON否则直接读取主文件文本。辅助文件由SkillFileTemplate处理其read()会先通过mcp.shared.path_security.safe_join做路径安全校验再根据 MIME 类型决定按文本还是二进制返回skill_provider.py#L72-L99。此外SkillResource.get_meta()会在资源元数据的fastmcp.skill字段中注入name与is_manifest信息方便上层工具识别资源归属。渐进式披露低成本发现Skills Provider 的核心设计思想是渐进式披露Progressive Disclosure客户端执行list_resources()时只拿到技能的名称与描述而不需要拉取完整正文——描述来源于 SKILL.md 的 YAML frontmatter无 frontmatter 时回退到首行文本。这样即使技能库规模很大发现阶段的网络与解析成本也保持极低。frontmatter 的解析在 _common.py 的parse_frontmatter中实现采用轻量手工解析支持---包裹的键值对、带引号字符串、以及[a, b, c]形式的列表如示例中的tags: [document, pdf, extraction]不做复杂 YAML 类型推导因此解析速度快且无额外依赖。辅助文件的可见性由supporting_files参数控制取值二选一template默认辅助文件通过ResourceTemplate暴露不出现在list_resources()结果中需通过模板 URI 按需读取——保持发现列表干净resources每个辅助文件作为独立Resource暴露直接可见于list_resources()——适合需要完整目录感知的场景。from fastmcp.server.providers.skills import SkillsDirectoryProvider SkillsDirectoryProvider(rootsskills_dir, supporting_filesresources)Manifest让客户端能够整包下载_manifest资源提供了一份 JSON 文件清单格式如下{ skill: pdf-processing, files: [ {path: SKILL.md, size: 1234, hash: sha256:abc...}, {path: reference.md, size: 5678, hash: sha256:def...} ] }该清单由SkillResource._generate_manifest()依据SkillInfo.files实时合成skill_provider.py#L60-L69。文件信息来自scan_skill_files递归扫描技能目录下所有文件记录相对路径统一转为 POSIX 风格以保证跨平台 URI 一致、字节大小并用 SHA-256 计算内容哈希前缀sha256:见compute_file_hash。这份清单的价值在于客户端可以先读 manifest 了解技能包含哪些文件及其哈希再按需拉取或整体下载、校验完整性这是把技能打包迁移到本地的基础协议。实战四种挂载方式server.py 完整收录了四种常见挂载模式后三种以注释形式给出1. 单个技能from pathlib import Path from fastmcp import FastMCP from fastmcp.server.providers.skills import SkillProvider mcp FastMCP(My Skill) mcp.add_provider(SkillProvider(Path.home() / .claude/skills/pdf-processing)) mcp.run()2. 目录下全部技能from fastmcp.server.providers.skills import SkillsDirectoryProvider mcp FastMCP(Skills) mcp.add_provider(SkillsDirectoryProvider(rootsPath.home() / .claude / skills)) mcp.run()3. Claude Code 默认位置from fastmcp import FastMCP from fastmcp.server.providers.skills import ClaudeSkillsProvider mcp FastMCP(My Skills) mcp.add_provider(ClaudeSkillsProvider()) # 默认 ~/.claude/skills/ mcp.run()4. 多目录按优先级组合mcp.add_provider(SkillsDirectoryProvider(roots[ Path.cwd() / .claude/skills, # 项目级优先 Path.home() / .claude/skills, # 用户级兜底 ]))除 Claude 外vendor_providers.py 还提供了面向其他平台的同类便捷类全部是SkillsDirectoryProvider的薄封装仅预设根目录提供类默认根目录CursorSkillsProvider()~/.cursor/skills/VSCodeSkillsProvider()/CopilotSkillsProvider()~/.copilot/skills/CodexSkillsProvider()/etc/codex/skills/系统级与~/.codex/skills/用户级系统级优先GeminiSkillsProvider()~/.gemini/skills/GooseSkillsProvider()~/.config/agents/skills/OpenCodeSkillsProvider()~/.config/opencode/skills/这意味着同一个 FastMCP 服务器可以把多平台、多路径的技能源聚合到一个统一的skill://资源命名空间里。客户端调用链发现、读取与下载基础读取流程client.py 演示了标准的调用序列resources await client.list_resources() # 发现技能名 描述 templates await client.list_resource_templates() # 查看辅助文件模板 main await client.read_resource(skill://pdf-processing/SKILL.md) # 读主文件 manifest await client.read_resource(skill://pdf-processing/_manifest) # 读清单 ref await client.read_resource(skill://pdf-processing/reference.md) # 按模板读辅助文件高级工具list_skills 与 sync_skillsutilities/skills.py 提供了一套开箱即用的客户端工具把上述流程封装成四个异步函数list_skills(client) - list[SkillSummary]通过识别skill://{name}/SKILL.mdURI 模式从list_resources()结果中提取技能名、描述与 URIget_skill_manifest(client, skill_name) - SkillManifest读取并解析_manifest返回name与files含path/size/hashdownload_skill(client, skill_name, target_dir, *, overwriteFalse)依据 manifest 逐个拉取文件并写入本地目录返回技能目录路径sync_skills(client, target_dir, *, overwriteFalse)遍历所有技能调用download_skill跳过已存在的目录。download_skills.py 用 Rich 渲染了完整演示先list_skills以表格展示服务器上可用的技能清单再sync_skills将全部技能下载到临时目录并用树形结构打印结果。值得强调的是这些工具内置的多层安全防线均可在 utilities/skills.py 中查到download_skill先校验目标目录不逃逸target_diris_relative_to检查防止恶意技能名造成路径穿越下载每个文件前拒绝绝对路径与逃逸技能目录的相对路径服务端SkillFileTemplate.read()侧同样通过safe_join拦截目录穿越、绝对路径注入、空字节与符号链接逃逸文本内容以 UTF-8 写入二进制内容经 base64 解码后写入未知内容类型直接跳过。参数速查与适用前提SkillsDirectoryProvider的完整构造参数directory_provider.py#L55-L61参数类型默认值说明rootsstr \| Path \| Sequence必填技能根目录可传单个路径或多个路径按顺序取优先级reloadboolFalse为True时每次请求重新扫描磁盘适合技能会动态增删的场景main_file_namestrSKILL.md判定技能文件夹的主文件名可自定义supporting_filestemplate \| resourcestemplate辅助文件的暴露方式模板默认隐藏或显式资源各厂商便捷类与ClaudeSkillsProvider仅暴露reload与supporting_files两个参数其余均已固定。两点适用说明其一frontmatter 采用轻量解析复杂 YAML 类型嵌套结构、对象等不会被完整还原请保持技能元数据的扁平键值形态其二SkillProvider面向技能目录这一既有约定主文件 辅助文件若你的资源组织方式与之不同FastMCP 的通用 Resource 与 ResourceTemplate 体系仍是更基础的选择。从整体设计看Skills Provider 的价值在于把技能即文件目录这一事实标准化为skill://协议服务端零成本接入任何 MCP 客户端都能发现、浏览并整包下载从而打通技能在不同 Agent 工具链之间的可移植性。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 FastMCP Skills Provider 将 Agent Skills 发布为 MCP 资源：架构解析与端到端实践
使用 FastMCP Skills Provider 将 Agent Skills 发布为 MCP 资源架构解析与端到端实践【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本指南以 examples/skills 示例为入口讲解如何在 FastMCP 项目中把 AI 编程助手如 Claude Code的技能Skills目录通过 Provider 机制暴露为标准 MCP 资源Resources并支持客户端发现—读取—下载的完整闭环。读完本文你将掌握SkillProvider、SkillsDirectoryProvider、ClaudeSkillsProvider等核心类的用法、skill://资源寻址协议、manifest 合成机制以及配套客户端工具list_skills/sync_skills的实战调用方式。示例概览与目录结构examples/skills是一个自包含的演示目录它把一个典型 Agent Skills 生态完整搬到了 FastMCP 里服务端负责暴露技能客户端负责发现与读取工具脚本负责批量下载并附带两份示例技能文件供直接运行验证。目录结构如下examples/skills/ ├── README.md # 本文档 ├── server.py # 暴露技能的 MCP 服务器 ├── client.py # 发现并读取技能的示例客户端 ├── download_skills.py # 从服务器批量下载技能的客户端工具示例 └── sample_skills/ # 示例技能目录 ├── pdf-processing/ │ ├── SKILL.md # 技能主文件 │ └── reference.md # 辅助文档 └── code-review/ └── SKILL.md # 技能主文件其中sample_skills/pdf-processing/SKILL.md演示了带 YAML frontmatter 的技能文件包含description、version、tags字段正文用## Capabilities、## Usage描述能力并在末尾通过相对链接[reference.md](https://link.gitcode.com/i/c9c062a3129bfd0d1c3cafd365d38755)指向辅助文档code-review/SKILL.md则是一个纯指南型技能以评审清单的形式组织内容。这两份文件的形态就是 FastMCP Skills Provider 能直接消费的标准输入。快速运行示例示例提供了三种启动方式均基于仓库根目录执行启动服务器uv run python examples/skills/server.py另开终端运行发现/读取客户端uv run python examples/skills/client.py运行批量下载演示内部自建内存服务器不依赖外部进程uv run python examples/skills/download_skills.pyserver.py 创建了名为Skills Server的 FastMCP 实例并默认通过SkillsDirectoryProvider(rootsskills_dir, reloadTrue)挂载sample_skills目录client.py 则直接复用同一个 Provider 构造内存服务器再以Client(mcp)连接完整演示了列表资源 → 列表模板 → 读主文件 → 读 manifest → 读辅助文件的调用链全程无需真实网络进程。三层 Provider 架构Skills 体系采用两层抽象由 skills/init.py 统一导出Provider职责源码位置SkillProvider处理单个技能文件夹将其内文件暴露为资源skill_provider.pySkillsDirectoryProvider扫描目录为每个含主文件的子文件夹创建一个SkillProviderdirectory_provider.pyClaudeSkillsProvider面向 Claude Code 技能的便捷子类默认根目录为~/.claude/skills/claude_provider.pySkillsDirectoryProvider继承自AggregateProvider在初始化时或reloadTrue时每次请求扫描每个根目录下的子文件夹凡是存在主文件默认SKILL.md的目录就视为一个技能并生成对应SkillProvider。从源码看directory_provider.py#L76-L116扫描逻辑有几个值得注意的行为非目录、缺少主文件的子目录会被静默跳过同名技能采用先到先得去重策略——多根目录场景下更靠前的根目录拥有更高优先级单个技能加载失败FileNotFoundError/PermissionError/OSError不会拖垮整个 Provider而是记录异常后继续文件遍历使用排序后的rglob保证跨平台输出顺序稳定见 _common.py 的scan_skill_files。ClaudeSkillsProvider只是把根目录固定为Path.home() / .claude / skills其余参数原样透传给父类。每个技能暴露为三类资源对于一个名为{name}的技能Provider 会暴露以下资源形态主文件资源skill://{name}/SKILL.md——返回技能主文件的文本内容合成 manifest 资源skill://{name}/_manifest——返回 JSON 文件清单详见下文辅助文件默认通过ResourceTemplateskill://{name}/{path}提供也可配置为显式Resource列表。主文件与 manifest 由SkillResource实现skill_provider.py#L37-L69当is_manifestTrue时read()动态生成 JSON否则直接读取主文件文本。辅助文件由SkillFileTemplate处理其read()会先通过mcp.shared.path_security.safe_join做路径安全校验再根据 MIME 类型决定按文本还是二进制返回skill_provider.py#L72-L99。此外SkillResource.get_meta()会在资源元数据的fastmcp.skill字段中注入name与is_manifest信息方便上层工具识别资源归属。渐进式披露低成本发现Skills Provider 的核心设计思想是渐进式披露Progressive Disclosure客户端执行list_resources()时只拿到技能的名称与描述而不需要拉取完整正文——描述来源于 SKILL.md 的 YAML frontmatter无 frontmatter 时回退到首行文本。这样即使技能库规模很大发现阶段的网络与解析成本也保持极低。frontmatter 的解析在 _common.py 的parse_frontmatter中实现采用轻量手工解析支持---包裹的键值对、带引号字符串、以及[a, b, c]形式的列表如示例中的tags: [document, pdf, extraction]不做复杂 YAML 类型推导因此解析速度快且无额外依赖。辅助文件的可见性由supporting_files参数控制取值二选一template默认辅助文件通过ResourceTemplate暴露不出现在list_resources()结果中需通过模板 URI 按需读取——保持发现列表干净resources每个辅助文件作为独立Resource暴露直接可见于list_resources()——适合需要完整目录感知的场景。from fastmcp.server.providers.skills import SkillsDirectoryProvider SkillsDirectoryProvider(rootsskills_dir, supporting_filesresources)Manifest让客户端能够整包下载_manifest资源提供了一份 JSON 文件清单格式如下{ skill: pdf-processing, files: [ {path: SKILL.md, size: 1234, hash: sha256:abc...}, {path: reference.md, size: 5678, hash: sha256:def...} ] }该清单由SkillResource._generate_manifest()依据SkillInfo.files实时合成skill_provider.py#L60-L69。文件信息来自scan_skill_files递归扫描技能目录下所有文件记录相对路径统一转为 POSIX 风格以保证跨平台 URI 一致、字节大小并用 SHA-256 计算内容哈希前缀sha256:见compute_file_hash。这份清单的价值在于客户端可以先读 manifest 了解技能包含哪些文件及其哈希再按需拉取或整体下载、校验完整性这是把技能打包迁移到本地的基础协议。实战四种挂载方式server.py 完整收录了四种常见挂载模式后三种以注释形式给出1. 单个技能from pathlib import Path from fastmcp import FastMCP from fastmcp.server.providers.skills import SkillProvider mcp FastMCP(My Skill) mcp.add_provider(SkillProvider(Path.home() / .claude/skills/pdf-processing)) mcp.run()2. 目录下全部技能from fastmcp.server.providers.skills import SkillsDirectoryProvider mcp FastMCP(Skills) mcp.add_provider(SkillsDirectoryProvider(rootsPath.home() / .claude / skills)) mcp.run()3. Claude Code 默认位置from fastmcp import FastMCP from fastmcp.server.providers.skills import ClaudeSkillsProvider mcp FastMCP(My Skills) mcp.add_provider(ClaudeSkillsProvider()) # 默认 ~/.claude/skills/ mcp.run()4. 多目录按优先级组合mcp.add_provider(SkillsDirectoryProvider(roots[ Path.cwd() / .claude/skills, # 项目级优先 Path.home() / .claude/skills, # 用户级兜底 ]))除 Claude 外vendor_providers.py 还提供了面向其他平台的同类便捷类全部是SkillsDirectoryProvider的薄封装仅预设根目录提供类默认根目录CursorSkillsProvider()~/.cursor/skills/VSCodeSkillsProvider()/CopilotSkillsProvider()~/.copilot/skills/CodexSkillsProvider()/etc/codex/skills/系统级与~/.codex/skills/用户级系统级优先GeminiSkillsProvider()~/.gemini/skills/GooseSkillsProvider()~/.config/agents/skills/OpenCodeSkillsProvider()~/.config/opencode/skills/这意味着同一个 FastMCP 服务器可以把多平台、多路径的技能源聚合到一个统一的skill://资源命名空间里。客户端调用链发现、读取与下载基础读取流程client.py 演示了标准的调用序列resources await client.list_resources() # 发现技能名 描述 templates await client.list_resource_templates() # 查看辅助文件模板 main await client.read_resource(skill://pdf-processing/SKILL.md) # 读主文件 manifest await client.read_resource(skill://pdf-processing/_manifest) # 读清单 ref await client.read_resource(skill://pdf-processing/reference.md) # 按模板读辅助文件高级工具list_skills 与 sync_skillsutilities/skills.py 提供了一套开箱即用的客户端工具把上述流程封装成四个异步函数list_skills(client) - list[SkillSummary]通过识别skill://{name}/SKILL.mdURI 模式从list_resources()结果中提取技能名、描述与 URIget_skill_manifest(client, skill_name) - SkillManifest读取并解析_manifest返回name与files含path/size/hashdownload_skill(client, skill_name, target_dir, *, overwriteFalse)依据 manifest 逐个拉取文件并写入本地目录返回技能目录路径sync_skills(client, target_dir, *, overwriteFalse)遍历所有技能调用download_skill跳过已存在的目录。download_skills.py 用 Rich 渲染了完整演示先list_skills以表格展示服务器上可用的技能清单再sync_skills将全部技能下载到临时目录并用树形结构打印结果。值得强调的是这些工具内置的多层安全防线均可在 utilities/skills.py 中查到download_skill先校验目标目录不逃逸target_diris_relative_to检查防止恶意技能名造成路径穿越下载每个文件前拒绝绝对路径与逃逸技能目录的相对路径服务端SkillFileTemplate.read()侧同样通过safe_join拦截目录穿越、绝对路径注入、空字节与符号链接逃逸文本内容以 UTF-8 写入二进制内容经 base64 解码后写入未知内容类型直接跳过。参数速查与适用前提SkillsDirectoryProvider的完整构造参数directory_provider.py#L55-L61参数类型默认值说明rootsstr \| Path \| Sequence必填技能根目录可传单个路径或多个路径按顺序取优先级reloadboolFalse为True时每次请求重新扫描磁盘适合技能会动态增删的场景main_file_namestrSKILL.md判定技能文件夹的主文件名可自定义supporting_filestemplate \| resourcestemplate辅助文件的暴露方式模板默认隐藏或显式资源各厂商便捷类与ClaudeSkillsProvider仅暴露reload与supporting_files两个参数其余均已固定。两点适用说明其一frontmatter 采用轻量解析复杂 YAML 类型嵌套结构、对象等不会被完整还原请保持技能元数据的扁平键值形态其二SkillProvider面向技能目录这一既有约定主文件 辅助文件若你的资源组织方式与之不同FastMCP 的通用 Resource 与 ResourceTemplate 体系仍是更基础的选择。从整体设计看Skills Provider 的价值在于把技能即文件目录这一事实标准化为skill://协议服务端零成本接入任何 MCP 客户端都能发现、浏览并整包下载从而打通技能在不同 Agent 工具链之间的可移植性。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考