Skill MCP

🚀 技能管理MCP服务器

技能管理MCP服务器是一个模型上下文协议（MCP）服务器，它使Claude能够管理存储在 ~/.skill-mcp/skills 中的技能。该系统允许Claude以编程方式创建、编辑、运行和管理技能，包括使用环境变量执行技能脚本。

🚀 快速开始

1. 安装uv

本项目使用 uv 进行快速、可靠的Python包管理。

# 安装uv（包含uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh

2. 配置MCP客户端

将MCP服务器添加到您的配置中。服务器将通过 uvx 从PyPI自动下载并运行。

• Claude桌面版：编辑配置文件
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json
• Cursor：编辑配置文件
  • macOS：~/.cursor/mcp.json
  • Windows：%USERPROFILE%\.cursor\mcp.json
  • Linux：~/.cursor/mcp.json

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ]
    }
  }
}

就是这样！无需安装 - uvx 将自动从PyPI下载并运行最新版本。

3. 重启MCP客户端

重启Claude桌面版或Cursor以加载MCP服务器。

4. 测试

在新的对话中输入：

List all available skills

Claude应该使用 skill-mcp 工具显示 ~/.skill-mcp/skills/ 中的技能。

✨ 主要特性

🚀 统一的多技能执行（使用MCP进行代码执行）

• 一次构建，随处组合：执行Python代码，可在单次运行中无缝组合多个技能。

# 一次执行，统一多个技能！
# 从计算器、数据处理器和天气技能中导入
from math_utils import calculate_average          # 计算器技能
from json_fetcher import fetch_json                # 数据处理器技能
from weather_api import get_forecast               # 天气技能

# 获取天气数据
weather = fetch_json('https://api.weather.com/cities')

# 使用计算器工具计算平均值
temps = [city['temp'] for city in weather['cities']]
avg_temp = calculate_average(temps)

# 获取详细预报
forecast = get_forecast('London')
print(f"Average temperature: {avg_temp}°F")
print(f"London forecast: {forecast}")

• 强大之处：
  • ✅ 上下文高效：自动聚合所有引用技能的依赖项和环境变量。
  • ✅ 可组合：像搭建积木一样混合和匹配任何技能的工具。
  • ✅ 无冗余：在库技能中声明一次PEP 723依赖项，可在任何地方重复使用。
  • ✅ 渐进式披露：仅在需要时加载所需的技能。
  • ✅ 遵循Anthropic的MCP模式：使用MCP进行代码执行，实现高效代理。
• 效率提升：
  • 📉 与一次性加载所有工具相比，渐进式发现工具时减少98.7%的令牌使用。
  • 🔄 中间结果保留在代码中，处理大型数据集时不会使上下文膨胀。
  • ⚡ 单次执行，将复杂的多步骤工作流放在一个代码块中，而不是链式调用工具。

🔓 不局限于Claude界面

与Claude界面不同，该系统使用 模型上下文协议（MCP），具有以下特点：

• ✅ 通用：可与Claude桌面版、claude.ai、Cursor和任何支持MCP的客户端一起使用。
• ✅ 不依赖Claude：相同的技能可在所有支持MCP的地方使用。
• ✅ 面向未来：不依赖Claude的生态系统或政策变化。
• ✅ 本地优先：完全控制您的技能和数据。

🎯 技能随处可用

您的技能可以在以下环境中运行：

• Cursor：支持MCP的集成开发环境。
• Claude桌面版：支持MCP的原生应用程序。
• claude.ai：支持MCP的Web界面。
• 任何MCP客户端：不断发展的兼容应用程序生态系统。

📦 独立且模块化

• ✅ 每个技能都是自包含的，有自己的文件、脚本和环境。
• ✅ 不依赖Claude的专有功能。
• ✅ 可以进行版本控制、共享和在项目间重用。
• ✅ 标准的MCP协议确保兼容性。

🔄 在所有MCP客户端之间共享技能

• ✅ 一个技能目录，多个客户端：创建一次，随处使用。
• ✅ Cursor和Claude中使用相同的技能：无需重复。
• ✅ 无缝切换：在工具之间切换时无需重新配置。
• ✅ 一致的体验：技能在所有MCP客户端中的工作方式相同。
• ✅ 集中管理：在一处更新技能，所有地方都可用。

🤖 由大语言模型管理的技能（无需手动复制粘贴）

❌ 旧方式：手动流程
   1. 在本地创建技能文件
   2. 压缩技能文件夹
   3. 上传到Claude界面
   4. 等待处理
   5. 难以修改或进行版本控制

✅ 新方式：由大语言模型以编程方式管理
   1. 告诉Claude：“Create a new skill called 'data-processor'”
   2. Claude创建技能目录和SKILL.md
   3. 告诉Claude：“Add a Python script to process CSVs”
   4. Claude创建并测试脚本
   5. 告诉Claude：“Set the API key for this skill”
   6. Claude更新.env文件
   7. 告诉Claude：“Run the script with this data”
   8. Claude立即执行并显示结果！

• 主要优点：
  • ✅ 无需手动文件操作：大语言模型处理创建、编辑和删除。
  • ✅ 即时更改：无需上传/下载/重新加载周期。
  • ✅ 完整的版本控制：技能是普通文件，可使用git。
  • ✅ 易于修改：大语言模型可以即时编辑脚本。
  • ✅ 可测试：大语言模型可以立即创建并运行脚本。
  • ✅ 协作性：团队可以通过MCP共同开发技能。

📦 安装指南

从PyPI安装

若要全局安装该软件包（可选）：

pip install skill-mcp

或者使用 uvx 无需安装即可运行（推荐）：

uvx --from skill-mcp skill-mcp-server

开发环境设置

如果您想贡献代码或从源代码运行：

# 克隆仓库
git clone https://github.com/fkesheh/skill-mcp.git
cd skill-mcp

# 安装依赖项
uv sync

# 运行测试
uv run pytest

# 在本地运行服务器
uv run -m skill_mcp.server

若要在MCP客户端配置中使用本地开发版本：

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/skill-mcp",
        "-m",
        "skill_mcp.server"
      ]
    }
  }
}

💻 使用示例

创建新技能

用户：“Create a new skill called 'pdf-processor' that can rotate and merge PDFs”

Claude将：
1. 创建技能目录和SKILL.md
2. 添加任何必要的脚本
3. 测试脚本
4. 指导您设置任何所需的依赖项

管理环境变量

用户：“I need to set up a GitHub API token for my GitHub skills”

Claude将：
1. 指导您将其添加到技能的.env文件中
2. 使用 `read_skill_env` 列出可用的键
3. 确认脚本可以通过 `os.environ` 使用它

运行技能脚本

用户：“Run the data processing script from my analytics skill”

Claude将：
1. 列出可用的技能和脚本
2. 使用环境变量执行脚本
3. 向您显示输出和任何错误

修改现有技能

用户：“Add a new reference document about our API schema to the company-knowledge skill”

Claude将：
1. 读取现有技能结构
2. 创建新的参考文件
3. 如果需要，更新SKILL.md以引用它

📚 详细文档

可用的MCP工具

服务器为Claude提供了以下统一的CRUD工具：

CRUD工具操作

skill_crud 操作

• list：列出所有技能，包括描述、路径和验证状态（支持文本/正则搜索）。
• get：获取全面的技能信息：SKILL.md内容、所有文件、脚本、环境变量。
• create：从模板（基本、Python、Bash、Node.js）创建新技能。
• delete：删除技能目录（需要确认）。
• validate：验证技能结构并获取诊断信息。
• list_templates：列出所有可用的技能模板及其描述。

skill_files_crud 操作

• read：读取技能目录中的一个或多个文件（支持批量读取）。
• create：创建一个或多个文件（自动创建父目录，支持原子批量创建）。
• update：更新一个或多个现有文件（支持批量更新）。
• delete：永久删除文件（防止路径遍历，不能删除SKILL.md）。

skill_env_crud 操作

• read：列出技能的环境变量键（为安全起见，隐藏值）。
• set：设置一个或多个环境变量（与现有变量合并）。
• delete：删除一个或多个环境变量。
• clear：清除技能的所有环境变量。

脚本执行

• run_skill_script：执行脚本，自动检测PEP 723依赖项并注入环境变量。
• execute_python_code：直接执行Python代码（支持PEP 723依赖项和跨技能导入）。

高级配置

自定义技能目录

可以使用 SKILL_MCP_DIR 环境变量自定义技能目录。如果未设置，默认为 ~/.skill-mcp/skills。

• 通过环境变量设置（推荐）：

# 临时设置，仅对当前会话有效
export SKILL_MCP_DIR="/custom/path/to/skills"

# 永久设置，在shell配置文件中（如~/.bashrc、~/.zshrc等）
echo 'export SKILL_MCP_DIR="/custom/path/to/skills"' >> ~/.zshrc

• 在MCP客户端配置中设置： 对于Claude桌面版或Cursor，将环境变量添加到MCP配置中：

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ],
      "env": {
        "SKILL_MCP_DIR": "/custom/path/to/skills"
      }
    }
  }
}

注意：

• 如果目录不存在，将自动创建。
• 使用自定义目录的绝对路径。
• 所有技能都将存储在配置的目录中。
• 没有全局秘密文件；环境变量存储在每个技能的 .env 文件中。

资源限制

资源限制在 src/skill_mcp/core/config.py 中定义：

MAX_FILE_SIZE = 1_000_000      # 文件读取限制（1MB）
MAX_OUTPUT_SIZE = 100_000      # 脚本输出限制（100KB）
SCRIPT_TIMEOUT_SECONDS = 30    # 脚本执行超时时间

要修改这些限制，需要分叉仓库并在配置文件中调整常量。

🔧 技术细节

包结构

src/skill_mcp/
├── server.py              # MCP服务器入口点
├── models.py              # Pydantic输入/输出模型（向后兼容）
├── models_crud.py         # 统一的CRUD输入模型
├── core/
│   ├── config.py          # 配置常量
│   └── exceptions.py      # 自定义异常类型
├── services/
│   ├── env_service.py     # 环境变量CRUD
│   ├── file_service.py    # 文件CRUD操作
│   ├── skill_service.py   # 技能发现和元数据
│   ├── script_service.py  # 脚本执行和PEP 723
│   └── template_service.py # 模板管理
├── utils/
│   ├── path_utils.py      # 安全路径验证
│   ├── yaml_parser.py     # YAML前置元数据解析
│   └── script_detector.py # 脚本能力检测
└── tools/
    ├── skill_crud.py      # 统一的技能CRUD工具
    ├── skill_files_crud.py # 统一的文件CRUD工具
    ├── skill_env_crud.py  # 统一的环境变量CRUD工具
    └── script_tools.py    # 脚本执行工具

tests/
├── conftest.py            # Pytest测试夹具
└── 20+ 个测试模块       # 145个测试（86%覆盖率通过）

新特性

统一的CRUD架构

• ✅ 3个统一的CRUD工具：取代9个以上的单独工具（skill_crud、skill_files_crud、skill_env_crud）。
• ✅ 批量操作：原子性地创建/更新/删除多个文件。
• ✅ 一致的模式：所有工具遵循相同的基于操作的模型。
• ✅ 更好的错误处理：所有操作的统一错误响应。

直接Python执行（多技能统一）

• 🚀 execute_python_code：在一次执行中统一多个技能（Anthropic推荐的MCP模式）。
• ✅ 跨技能导入：从任何技能导入模块作为可重用库。
• ✅ 自动依赖聚合：自动合并所有导入技能的依赖项。
• ✅ 自动环境加载：自动加载所有引用技能的 .env 文件。
• ✅ 支持PEP 723：内联依赖声明。
• 📉 减少98.7%的令牌使用：渐进式加载技能，而不是一次性加载所有技能。

增强功能

• ✅ 技能模板：从模板（基本、Python、Bash、Node.js）创建技能。
• ✅ 模板发现：列出所有可用模板及其描述。
• ✅ 技能验证：验证技能结构并获取诊断信息。
• ✅ 搜索功能：通过名称/描述使用文本或正则表达式搜索技能。
• ✅ 命名空间路径：文件路径显示为 "skill_name:file.py"，以提高清晰度。
• ✅ 可配置的技能目录：使用 SKILL_MCP_DIR 环境变量。

测试结果

单元测试：145/145通过 ✅

覆盖率：86%（959/1120条语句被覆盖） 对所有模块进行了全面的测试覆盖：

测试组织：

• ✅ CRUD操作：对所有操作（创建、读取、更新、删除）进行全面测试。
• ✅ 批量操作：对文件操作进行原子事务测试。
• ✅ 模板系统：模板发现、验证和创建。
• ✅ 路径安全：防止目录遍历和验证。
• ✅ 支持PEP 723：依赖项检测和聚合。
• ✅ 集成测试：完整的MCP服务器工作流测试。

手动测试：全部通过 ✅

• ✅ 列出带有YAML描述的技能并具有搜索功能。
• ✅ 获取包含SKILL.md内容的全面技能详细信息。
• ✅ 从模板（基本、Python、Bash、Node.js）创建技能。
• ✅ 读取/创建/更新/删除文件（单个和批量）。
• ✅ 读取/设置/删除/清除环境变量。
• ✅ 执行带有自动依赖项（PEP 723）的脚本。
• ✅ 直接执行带有跨技能导入的Python代码。
• ✅ 从导入的技能模块聚合依赖项。
• ✅ 从引用的技能加载环境变量。

验证清单

• ✅ 服务器成功导入。
• ✅ 所有5个统一的CRUD工具已注册并可调用。
• ✅ 145/145个单元测试通过（86%覆盖率）。
• ✅ 所有手动测试通过。
• ✅ MCP客户端配置正常工作（Claude桌面版、Cursor）。
• ✅ 软件包已部署到PyPI并处于活动状态。
• ✅ 脚本使用PEP 723依赖项成功执行。
• ✅ 文件操作正常工作（包括批量操作）。
• ✅ 环境变量操作正常工作（CRUD操作）。
• ✅ 模板系统正常工作（创建、列出、验证）。
• ✅ 直接Python执行与跨技能导入正常工作。
• ✅ 与现有技能向后兼容。

📄 许可证

本项目采用MIT许可证。

版权所有 (c) 2025

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人，允许其无限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向其提供软件的人这样做，但需遵守以下条件：

上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。

软件按“原样”提供，不附带任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对因合同、侵权或其他方式引起的任何索赔、损害或其他责任负责，无论是在与软件或软件的使用或其他交易相关的任何行动中。

贡献说明

这是一个供个人使用的自定义工具。您可以自由分叉并根据自己的需求进行调整。

支持

如果您在设置过程中遇到问题或有疑问，请参考以下文档：

• Claude的MCP文档：https://modelcontextprotocol.io
• MCP Python SDK文档：https://github.com/modelcontextprotocol/python-sdk

⚠️ 重要提示

最佳实践

技能开发

• 遵循标准的技能结构（SKILL.md、scripts/、references/、assets/）。
• 保持SKILL.md简洁明了。
• 使用渐进式披露（将大型文档拆分为参考文件）。
• 创建脚本后立即进行测试。

环境变量

• 使用描述性名称（如 API_KEY、DATABASE_URL）。
• 切勿记录或打印敏感值。
• 设置 .env 文件的权限：chmod 600 ~/.skill-mcp/skills/<skill-name>/.env。

脚本开发

• 使用有意义的退出代码（0表示成功）。
• 向标准输出打印有用的消息。
• 向标准错误输出打印错误信息。
• 包含错误处理。
• 对于有依赖项的Python脚本：使用内联元数据（PEP 723）。

# /// script
# dependencies = [
#   "package-name>=version",
# ]
# ///

• 没有元数据的脚本使用系统Python解释器。
• 有元数据的脚本通过uv自动获得隔离环境。

安全管理敏感机密

为防止大语言模型访问您的敏感凭证：

# 直接在文件系统上编辑技能的.env文件（大语言模型无法访问您的本地文件）
nano ~/.skill-mcp/skills/my-skill/.env

# 手动添加您的机密信息
API_KEY=your-actual-api-key-here
DATABASE_PASSWORD=your-password-here
OAUTH_TOKEN=your-token-here

# 保护文件安全
chmod 600 ~/.skill-mcp/skills/my-skill/.env

• 重要原因：
  • ✅ 大语言模型永远不会看到您的敏感值。
  • ✅ 机密信息仅保留在您的系统中。
  • ✅ 没有凭证出现在日志或输出中的风险。
  • ✅ 完全控制敏感数据。
  • ✅ 可以与 git-secret 或类似工具一起用于版本控制。
• 工作流程：
  1. Claude创建技能结构和脚本。
  2. 您手动将敏感值添加到 .env 文件中。
  3. Claude可以读取 .env 键（看不到值）并使用它们。
  4. 脚本在运行时通过环境变量访问机密信息。
• 示例：

# 步骤1：Claude通过MCP创建技能 "api-client"
# 您说：“Create a new skill called 'api-client'”

# 步骤2：您手动保护机密信息
$ nano ~/.skill-mcp/skills/api-client/.env
API_KEY=sk-abc123def456xyz789
ENDPOINT=https://api.example.com

$ chmod 600 ~/.skill-mcp/skills/api-client/.env

# 步骤3：Claude现在可以安全地使用该技能
# 您说：“Run the API client script”
# Claude仅读取环境变量名称，并在脚本中使用它们
# 您的实际API密钥永远不会暴露给Claude

• ❌ 切勿这样做：
  • ❌ 告诉Claude您的实际API密钥或密码。
  • ❌ 要求Claude设置带有敏感值的环境变量。
  • ❌ 将机密信息存储在SKILL.md或其他跟踪文件中。
  • ❌ 使用 update_skill_env 工具处理真实的机密信息（仅用于非敏感配置）。
• ✅ 应该这样做：
  • ✅ 在您的系统上手动更新 .env 文件。
  • ✅ 将 .env 文件添加到 .gitignore 中。
  • ✅ 使用 chmod 600 限制文件访问。
  • ✅ 仅告诉Claude变量名称（例如，“the API key is in API_KEY”）。
  • ✅ 使机密信息与大语言模型交互完全分离。

验证大语言模型生成的代码

当Claude或其他大语言模型使用此MCP系统创建或修改技能和脚本时，在生产环境中运行之前，始终验证生成的代码：

安全考虑

• ⚠️ 始终审查生成的代码：大语言模型可能会出错或生成次优代码。
• ⚠️ 检查安全问题：查找硬编码的凭证、不安全的操作或漏洞。
• ⚠️ 彻底测试：首先在隔离环境中运行脚本。
• ⚠️ 验证权限：确保脚本具有适当的文件和系统权限。
• ⚠️ 监控依赖项：审查通过PEP 723安装的任何外部软件包。

大语言模型生成技能的最佳实践

1. 执行前审查：始终通读生成的脚本。
2. 在隔离环境中测试：在生产使用之前在安全环境中运行。
3. 使用版本控制：使用git跟踪所有更改以进行审计。
4. 实施错误处理：添加强大的错误处理和日志记录。
5. 设置资源限制：使用超时和资源约束。
6. 以最小权限运行：不要以root或提升的权限运行技能。
7. 验证输入：清理任何用户提供的数据。
8. 审计日志：审查脚本实际执行的操作并跟踪其执行情况。

常见检查项

• ❌ 硬编码的API密钥、密码或令牌。
• ❌ 不安全的文件操作或路径遍历风险。
• ❌ 未验证的外部命令或shell注入风险。
• ❌ 缺少错误处理或边缘情况处理。
• ❌ 无限制的资源密集型操作。
• ❌ 不安全的反序列化（如 eval、pickle 等）。
• ❌ 请求过多权限。
• ❌ 不可信的外部依赖项。

有疑问时

• 要求Claude/大语言模型解释代码。
• 让其他人审查关键代码。
• 使用代码检查器和安全扫描工具。
• 在容器或虚拟机中运行以进行隔离。
• 在进行破坏性操作之前先进行只读操作。

请记住：大语言模型生成的代码只是一个起点。您的验证和审查对于安全性和可靠性至关重要。