MCP Skill Hub

🚀 MCP技能服务器

MCP 技能服务器是一个可用于生产环境的 模型上下文协议 (MCP) 服务器，它能够从挂载的卷中动态加载技能，并支持热重载。你可以通过一个命令完成安装，轻松开启使用之旅。

🚀 快速开始

使用 Docker（推荐）

1. 创建技能目录：

mkdir -p ~/claude-skills/my-first-skill

2. 创建技能文件：

cat > ~/claude-skills/my-first-skill/SKILL.md << 'EOF'
---
name: "my-first-skill"
description: "My first Claude skill"
---

# My First Skill

This is my first skill for Claude!

## Usage

Simply describe what your skill does here.
EOF

3. 运行服务器：

docker run -i --rm \
  -v ~/claude-skills:/skills:ro \
  mcp-skill-hub

使用 Poetry（开发环境）

1. 克隆并安装：

git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub
poetry install

2. 创建技能目录：

mkdir -p ~/claude-skills/my-first-skill
# 按照上述步骤创建 SKILL.md 文件

3. 运行服务器：

export MCP_SKILLS_DIR=~/claude-skills
poetry run mcp-skills

✨ 主要特性

• 动态技能加载：自动从指定目录发现并加载技能。
• 热重载：检测 SKILL.md 文件的更改，无需重启即可重新加载。
• 文件夹结构验证：强制执行最佳实践，并提供清晰的错误消息。
• 符合 MCP 协议：完整实现资源和工具。
• 适用于生产环境：具备全面的错误处理、日志记录和验证功能。
• 支持 Docker：可在容器中运行，并支持卷挂载。
• 类型安全：使用 Python 3.13 特性提供完整的类型提示。
• 测试完备：测试套件覆盖率超过 80%。

📦 安装指南

前提条件

• Python 3.13+（用于开发）
• Poetry 1.7+（用于依赖管理）
• Docker（可选，用于容器化部署）

使用 Poetry 安装

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

# 安装依赖
poetry install

# 验证安装
poetry run mcp-skills --help

构建 Docker 镜像

# 构建镜像
docker build -t mcp-skill-hub .

# 或者使用 docker-compose
docker-compose build

💻 使用示例

本地运行

# 设置技能目录
export MCP_SKILLS_DIR=/path/to/your/skills

# 运行服务器
poetry run mcp-skills

使用 Docker 运行

docker run -i --rm \
  -v /path/to/your/skills:/skills:ro \
  -e MCP_SKILLS_LOG_LEVEL=INFO \
  mcp-skill-hub

使用 Docker Compose 运行

# 编辑 docker-compose.yml 文件以设置技能目录路径
docker-compose up mcp-skills

与 Claude Desktop 集成

添加到你的 Claude Desktop 配置文件 (claude_desktop_config.json) 中：

{
  "mcpServers": {
    "skills": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/claude-skills:/skills:ro",
        "mcp-skill-hub"
      ]
    }
  }
}

或者使用 Poetry：

{
  "mcpServers": {
    "skills": {
      "command": "poetry",
      "args": ["run", "mcp-skills"],
      "cwd": "/path/to/mcp-skill-hub",
      "env": {
        "MCP_SKILLS_DIR": "/path/to/your/skills"
      }
    }
  }
}

⚠️ 重要提示

请确保你的 ${HOME}/claude-skills 目录包含技能文件夹，而不是单独的 SKILL.md 文件！

📚 详细文档

技能目录结构

关键要求：每个技能必须位于技能目录下的独立文件夹中。服务器仅识别遵循此结构的技能。

✅ 有效结构

your-skills-directory/
├── skill-one/
│   └── SKILL.md          ← 必需
├── skill-two/
│   ├── SKILL.md          ← 必需
│   └── examples/         ← 可选
│       └── example.py
└── skill-three/
    ├── SKILL.md
    ├── examples/
    │   └── demo.py
    └── templates/
        └── template.txt

❌ 无效结构（将被忽略）

your-skills-directory/
├── SKILL.md                  ❌ 不在文件夹中 - 将被跳过
├── random-file.txt           ❌ 不是技能文件夹
├── .hidden-folder/           ❌ 隐藏文件夹 - 将被跳过
│   └── SKILL.md
└── __pycache__/              ❌ 系统文件夹 - 将被跳过
    └── SKILL.md

文件夹命名约定

有效文件夹名称：

• 小写字母加连字符：my-skill-name
• 小写字母加下划线：excel_advanced
• 字母数字组合：skill-name-v2

无效（将被跳过）：

• 以 . 开头的隐藏文件夹
• 以 _ 开头的私有文件夹
• 系统文件夹：__pycache__、node_modules、.git 等

配置

通过以 MCP_SKILLS_ 为前缀的环境变量进行配置：

属性	详情
MCP_SKILLS_DIR	/skills
MCP_SKILLS_HOT_RELOAD	true
MCP_SKILLS_DEBOUNCE_DELAY	0.5
MCP_SKILLS_LOG_LEVEL	INFO
MCP_SKILLS_SCAN_DEPTH	1

示例 .env 文件

MCP_SKILLS_DIR=/path/to/skills
MCP_SKILLS_HOT_RELOAD=true
MCP_SKILLS_DEBOUNCE_DELAY=0.5
MCP_SKILLS_LOG_LEVEL=INFO

技能文件格式

技能在 SKILL.md 文件中使用 YAML 前置元数据进行定义：

最小示例

---
name: "my-skill"
description: "Brief description"
---

# My Skill

Your skill content here in Markdown.

完整示例

---
# 必需字段
name: "excel-advanced"
description: "Advanced Excel automation techniques"

# 版本和作者信息
version: "1.2.0"
author: "Your Name"
created: "2025-01-15"
updated: "2025-10-23"

# 依赖项
dependencies:
  python: ["openpyxl>=3.0.0", "pandas>=2.0.0"]
  system: ["libreoffice"]

# 分类
category: "office-automation"
tags: ["excel", "spreadsheet", "automation"]
complexity: "intermediate"  # beginner|intermediate|advanced

# 使用指南
when_to_use:
  - "Automating Excel report generation"
  - "Processing multiple Excel files"
  - "Creating complex formulas programmatically"

# 关联技能
related_skills: ["csv-processing", "data-analysis"]

# 示例
has_examples: true
example_files: ["examples/report_generator.py", "templates/report_template.xlsx"]
---

# Excel Advanced Automation

This skill covers advanced Excel automation techniques...

## Features

- Automated report generation
- Formula creation
- Bulk processing

## Examples

See `examples/report_generator.py` for a working example.

可用元数据字段

必需：

• name：唯一标识符（建议使用短横线分隔的小写字母）
• description：简要描述

可选：

• version：语义化版本号
• author：创建者姓名
• created, updated：ISO 日期格式（YYYY-MM-DD）
• dependencies：Python 包或系统工具
• category：主要分类，用于分组
• tags：标签数组，用于搜索
• complexity：初学者、中级或高级
• when_to_use：使用场景数组
• related_skills：相关技能名称
• has_examples：布尔标志
• example_files：示例文件路径（相对于技能文件夹）

MCP 资源和工具

资源

服务器公开以下 MCP 资源：

1. skill://catalog - 包含所有技能元数据的 JSON 目录
2. skill://{name} - 单个技能的 Markdown 内容

工具

提供四个工具用于与技能进行交互：

1. search_skills

按查询、类别、标签或复杂度搜索技能。

{
  "query": "excel",
  "category": "office-automation",
  "tag": "automation",
  "complexity": "intermediate"
}

2. reload_skills

手动触发从目录重新加载所有技能。

{}

3. get_skill_info

获取特定技能的元数据，而无需加载完整内容。

{
  "name": "excel-advanced"
}

4. list_skill_folders

列出技能目录中找到的所有有效技能文件夹。

{}

开发

设置开发环境

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

# 安装依赖（包括开发依赖）
poetry install

# 激活虚拟环境
poetry shell

运行测试

# 运行所有测试
poetry run pytest

# 运行测试并生成覆盖率报告
poetry run pytest --cov=mcp_skills --cov-report=html

# 运行特定测试文件
poetry run pytest tests/test_scanner.py

# 运行测试并输出详细信息
poetry run pytest -v

代码质量

# 格式化代码
poetry run black .

# 代码检查
poetry run ruff check .

# 类型检查
poetry run mypy src

# 运行所有质量检查
poetry run black . && poetry run ruff check . && poetry run mypy src

开发工作流程

1. 创建分支：

git checkout -b feature/my-feature

2. 进行更改并测试：

poetry run pytest
poetry run mypy src

3. 格式化和检查代码：

poetry run black .
poetry run ruff check .

4. 提交并推送：

git commit -m "Add feature: description"
git push origin feature/my-feature

项目结构

mcp-skill-hub/
├── src/mcp_skills/          # 源代码
│   ├── models/              # 数据模型
│   ├── parsers/             # 技能解析器
│   ├── storage/             # 存储模式
│   ├── scanner.py           # 目录扫描
│   ├── watcher.py           # 热重载监视器
│   ├── server.py            # MCP 服务器
│   ├── config.py            # 配置
│   └── __main__.py          # CLI 入口点
├── tests/                   # 测试套件
├── examples/                # 示例技能
├── docs/                    # 文档
└── pyproject.toml           # Poetry 配置

故障排除

常见问题

技能未加载

问题：服务器启动时没有加载任何技能。 解决方案：

1. 检查技能是否位于独立文件夹中：

/skills/my-skill/SKILL.md  ✓
/skills/SKILL.md           ✗

2. 验证文件夹名称不以 . 或 _ 开头。
3. 查看日志以获取详细错误消息。

热重载不起作用

问题：对 SKILL.md 文件的更改未被检测到。 解决方案：

1. 确保 MCP_SKILLS_HOT_RELOAD=true。
2. 检查文件名为 SKILL.md。
3. 验证文件位于有效技能文件夹中。
4. 在日志中查找文件监视器错误。

解析错误

问题：SKILL.md 文件解析失败。 解决方案：

1. 验证 YAML 前置元数据语法。
2. 确保前置元数据位于 --- 分隔符之间。
3. 检查必需字段（name、description）是否存在。
4. 使用 YAML 验证器检查语法。

验证命令

检查技能目录结构：

poetry run mcp-skills --validate

预期输出：

✓ /skills/excel-advanced: Valid skill
✓ /skills/python-automation: Valid skill
✗ /skills/SKILL.md: Error - Skills must be in folders
✗ /skills/.hidden: Skipped - Hidden folder
⚠ /skills/empty-folder: Warning - No SKILL.md found

Summary: 2 valid, 1 error, 1 warning, 1 skipped

日志记录

启用调试日志以获取详细信息：

export MCP_SKILLS_LOG_LEVEL=DEBUG
poetry run mcp-skills

日志包括：

• 文件夹结构验证消息
• 扫描进度和结果
• 解析成功和失败信息
• 热重载事件
• 详细错误上下文

贡献

欢迎贡献代码！请参阅 CONTRIBUTING.md 获取指南。

快速贡献指南

1. 分叉仓库
2. 创建功能分支
3. 进行更改并添加测试
4. 确保所有测试通过且代码已格式化
5. 提交拉取请求

代码标准

• Python 3.13+ 并使用类型提示
• 使用 Black 进行格式化（每行 88 个字符）
• 使用 Ruff 进行代码检查
• 使用 Mypy 进行类型检查（严格模式）
• 使用 Pytest 进行测试（覆盖率超过 80%）

版本发布

本项目通过 GitHub Actions 实现自动发布。

创建版本发布

1. 转到 Actions → Release 工作流
2. 点击 Run workflow
3. 选择版本升级类型：

• patch - 修复 bug（0.1.0 → 0.1.1）
• minor - 添加新功能（0.1.0 → 0.2.0）
• major - 重大更改（0.1.0 → 1.0.0）
• 或者指定确切版本（例如 1.2.3）

4. 选择 Docker 注册表 (docker.io 或 ghcr.io)
5. 点击 Run workflow

工作流将：

• ✅ 更新 pyproject.toml 中的版本号
• ✅ 创建 Git 标签和 GitHub 版本发布
• ✅ 构建并推送 Docker 镜像
• ✅ 运行测试以验证版本发布

Docker 镜像：

• Docker Hub：{username}/mcp-skill-hub:{version}
• GitHub：ghcr.io/{owner}/mcp-skill-hub:{version}

详细的版本发布文档请参阅 RELEASING.md。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 基于 MCP Python SDK 构建
• 受 Claude 中动态技能管理需求的启发
• 感谢所有贡献者！

---

⚠️ 重要提示

本服务器通过以下方式确保不会误解文件夹结构要求：

• 提供带有文件夹上下文的清晰错误消息
• 全面的日志记录
• 多级验证
• 详细的文档
• 可用的示例

每个技能必须位于独立文件夹中。这一设计决策确保了组织清晰、管理方便和结构明确。 🎯