MCP Skill Hub

🚀 MCP Skills Server

本サーバーは、マウントされたボリュームからスキルを動的に読み込み、ホットリロードをサポートする、本番環境で使用可能なModel Context Protocol (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

スキルファイル形式

スキルは、YAMLフロントマターを持つ SKILL.md ファイルで定義されます:

最小限の例

---
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: beginner, intermediate, または advanced
• when_to_use: 使用シナリオの配列
• related_skills: 関連するスキルの名前
• has_examples: ブール値のフラグ
• example_files: サンプルファイルのパス（スキルフォルダからの相対パス）

MCPリソースとツール

リソース

サーバーは、以下のMCPリソースを公開します:

1. skill://catalog - すべてのスキルのメタデータを含むJSONカタログ
2. skill://{name} - 個々のスキルのMarkdownコンテンツ

ツール

スキルとのやり取りに使用できる4つのツールがあります:

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 - バグ修正 (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における動的なスキル管理の必要性から着想を得ています
• すべてのコントリビューターに感謝します！

注: このサーバーは、以下の方法でフォルダ構造の要件を誤解することを防止します:

• フォルダのコンテキストを含む明確なエラーメッセージ
• 包括的なロギング
• 複数のレベルでの検証
• 詳細なドキュメント
• 実際のサンプル

各スキルは、独自のフォルダに配置する必要があります。この設計上の決定により、きれいな組織化、簡単な管理、および明確な構造が保証されます。 🎯