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_ 為前綴的環境變量進行配置：

示例 .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 中動態技能管理需求的啟發
• 感謝所有貢獻者！

⚠️ 重要提示

本服務器通過以下方式確保不會誤解文件夾結構要求：

• 提供帶有文件夾上下文的清晰錯誤消息
• 全面的日誌記錄
• 多級驗證
• 詳細的文檔
• 可用的示例

每個技能必須位於獨立文件夾中。這一設計決策確保了組織清晰、管理方便和結構明確。 🎯