MCP Skills Server

MCP Skills Server

マウントされたボリュームからスキルを動的に読み込んで公開し、ホットリロードをサポートする、本番環境対応のModel Context Protocol（MCP）サーバーです。

📦 MCP Registryで利用できます - 1つのコマンドでインストールできます！

特長

• スキルの動的読み込み：ディレクトリからスキルを自動的に検出して読み込みます
• ホットリロード：SKILL.md ファイルの変更を検出し、再起動せずに再読み込みします
• フォルダー構造の検証：明確なエラーメッセージでベストプラクティスを徹底します
• MCP プロトコル準拠：リソースとツールを完全に実装しています
• 本番環境対応：包括的なエラー処理、ロギング、検証機能を備えています
• Docker サポート：ボリュームをマウントしてコンテナー内で実行できます
• 型安全：Python 3.13 の機能を使用した完全な型ヒントを備えています
• 十分なテスト：包括的なテストスイートにより、コードカバレッジは 80% を超えています

目次

• スキルディレクトリの構造
• クイックスタート
• インストール
• 使い方
• 設定
• スキルファイルの形式
• MCP のリソースとツール
• 開発
• トラブルシューティング
• コントリビューション
• ライセンス

スキルディレクトリの構造

重要な要件：各スキルは、スキルディレクトリ内の専用フォルダーに配置する必要があります。この構造に従っているスキルのみがサーバーに認識されます。

✅ 有効な構造

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

❌ 無効な構造（無視されます）

your-skills-directory/
├── SKILL.md                  ❌ Not in a folder - WILL BE SKIPPED
├── random-file.txt           ❌ Not a skill folder
├── .hidden-folder/           ❌ Hidden folder - WILL BE SKIPPED
│   └── SKILL.md
└── __pycache__/              ❌ System folder - WILL BE SKIPPED
    └── SKILL.md

フォルダー名の規則

有効なフォルダー名：

• 小文字とハイフン：my-skill-name
• 小文字とアンダースコア：excel_advanced
• 英数字：skill-name-v2

無効（スキップされます）：

• . で始まる隠しフォルダー
• _ で始まるプライベートフォルダー
• システムフォルダー：__pycache__、node_modules、.git など

クイックスタート

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
# Create SKILL.md as shown above

3. サーバーを実行します：

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

インストール

前提条件

• Python 3.13 以降（開発用）
• Poetry 1.7 以降（依存関係管理用）
• Docker（任意。コンテナー化してデプロイする場合）

Poetry でインストールする

# Clone the repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies
poetry install

# Verify installation
poetry run mcp-skills --help

Docker イメージをビルドする

# Build the image
docker build -t mcp-skill-hub .

# Or use docker-compose
docker-compose build

使い方

ローカルで実行する

# Set the skills directory
export MCP_SKILLS_DIR=/path/to/your/skills

# Run the server
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 で実行する

# Edit docker-compose.yml to set your skills directory path
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 ファイルではなく、スキルフォルダーを配置してください！

設定

設定は、MCP_SKILLS_ をプレフィックスとする環境変数で行います。

変数	デフォルト	説明
MCP_SKILLS_DIR	/skills	スキルフォルダーを格納するルートディレクトリ
MCP_SKILLS_HOT_RELOAD	true	自動再読み込みを有効にします
MCP_SKILLS_DEBOUNCE_DELAY	0.5	再読み込みまでの待機時間（秒）
MCP_SKILLS_LOG_LEVEL	INFO	ログレベル（DEBUG、INFO、WARNING、ERROR）
MCP_SKILLS_SCAN_DEPTH	1	スキャンの深さ（常に 1）

.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.

完全な例

---
# Required fields
name: "excel-advanced"
description: "Advanced Excel automation techniques"

# Version and authorship
version: "1.2.0"
author: "Your Name"
created: "2025-01-15"
updated: "2025-10-23"

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

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

# Usage guidance
when_to_use:
  - "Automating Excel report generation"
  - "Processing multiple Excel files"
  - "Creating complex formulas programmatically"

# Relationships
related_skills: ["csv-processing", "data-analysis"]

# Examples
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：一意の識別子（kebab-case を推奨）
• 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 コンテンツ

ツール

スキルを操作するために、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

スキルディレクトリ内で見つかった、有効なスキルフォルダーをすべて一覧表示します。

{}

開発

開発環境のセットアップ

# Clone repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies (including dev dependencies)
poetry install

# Activate virtual environment
poetry shell

テストの実行

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcp_skills --cov-report=html

# Run specific test file
poetry run pytest tests/test_scanner.py

# Run with verbose output
poetry run pytest -v

コード品質

# Format code
poetry run black .

# Lint code
poetry run ruff check .

# Type checking
poetry run mypy src

# Run all quality checks
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/          # Source code
│   ├── models/              # Data models
│   ├── parsers/             # Skill parsers
│   ├── storage/             # Repository pattern
│   ├── scanner.py           # Directory scanning
│   ├── watcher.py           # Hot-reload watcher
│   ├── server.py            # MCP server
│   ├── config.py            # Configuration
│   └── __main__.py          # CLI entry point
├── tests/                   # Test suite
├── examples/                # Example skills
├── docs/                    # Documentation
└── pyproject.toml           # Poetry configuration

トラブルシューティング

よくある問題

スキルが読み込まれない

問題： サーバーの起動時にスキルが読み込まれません。

解決策：

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（strict モード）
• テストには 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 のもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。

謝辞

• MCP Python SDK を使用して構築されています
• Claude での動的なスキル管理の必要性から着想を得ました
• すべての貢献者に感謝します！

---

注： このサーバーでは、次の方法によってフォルダー構造の要件を誤解できないようにしています：

• フォルダーの情報を含む明確なエラーメッセージ
• 包括的なログ記録
• 複数のレベルでの検証
• 詳細なドキュメント
• 動作するサンプル

各スキルは必ず専用のフォルダーに配置する必要があります。この設計により、整理された構成、容易な管理、明確な構造を実現できます。🎯