MCP Skill Server

🚀 MCP Skill Server

現在、多くのコーディングアシスタントはネイティブでスキルをサポートしているため、スキルの探索のみを目的としたMCPサーバーは必要ありません。このパッケージの価値は、スキルの実行を決定論的かつデプロイ可能にすることです。固定されたエントリーポイントと制御された実行により、エディタで開発したスキルを非サンドボックスの本番環境で実行することができます。また、インクリメンタルなロードをサポートしているため、エージェントは必要に応じてスキルを探索し、最初にすべてをロードする必要はありません。

作業環境でエージェントのスキルを構築しましょう。Pythonスクリプトを書き、SKILL.mdを追加するだけで、エージェントはすぐにそれを使用できます。日々のワークフローの一環としてリアルタイムで反復開発できます。完成したら、同じスキルを本番環境にデプロイできます。書き直す必要はありません。

✨ 主な機能

なぜこのサーバーが必要なのか？

ほとんどのスキル開発は、コードを書く → デプロイする → ステージング環境のエージェントでテストする → 間違いに気付く → 再デプロイする → というサイクルです。これは遅く、開発中にスキルを実際に使用することができません。

MCP Skill Serverはこれを逆転させます。これはエディタ内、あなたのマシン上で実行されます。Claude Code、Cursor、またはClaude Desktopです。あなたはスキルを開発しながら、実際の作業でそれを使用することができます。この緊密なフィードバックループ（編集 → 保存 → 使用）により、人工的なテストシナリオではなく、自然に不足している部分を発見することができます。前提として、Claude Codeでうまく機能しないスキルは、より単純なエージェントでは機能しない可能性が高いと考えられます。

スキルが本番環境で生き残るために成熟する方法

Claudeのスキルにはすでにコンパニオンスクリプトを持たせることができますが、正式なエントリーポイントはありません。エージェントがどのように呼び出すかを決定します。これはローカル使用には適していますが、デプロイ可能ではありません。実行パスが固定されていないと、本番環境のMCPサーバーはスキルを確実に呼び出すことができません。

MCP Skill Serverは、SKILL.mdのフロントマターに宣言された**entryフィールド**（例：entry: uv run python my_script.py）を強制します。これにより、サーバーが制御する単一の固定エントリーポイントが得られます。コマンドとパラメーターは、スクリプトの--help出力から検出されます。これが真実の源であり、LLMによるコードの解釈ではありません。

1. Claude/コーディングアシスタントのスキル                → SKILL.md + スクリプト、ただし固定エントリーなし — エージェントが実行方法を決定
2. ローカルMCPスキル (+ エントリー)   → 固定されたエントリーポイント、--helpからのスキーマ、このサーバーを通じて日常的に使用可能
3. 本番環境                  → 同じスキル、同じエントリー — 企業のMCPサーバーにデプロイ

ローカルで磨き、本番環境に適用する

MCPサーバーに接続するすべてのエージェントは、同じインターフェース（list_skills、get_skill、run_skill）を取得します。したがって、どのエージェントが呼び出しても、スキルの説明、パラメーター名、ヘルプテキストは同じになります。ただし、異なるエージェントにはそれぞれ長所があります。ローカルで機能するスキルでも、本番環境のエージェントでテストする必要があります。

1. 自分で使用する — スキルを構築し、Claude CodeまたはCursorを通じて日常的に使用します。エージェントがスキルを誤用する場合は、説明とパラメーター名を修正します。
2. 弱いモデルでテストする — 小さいモデルを試して、インターフェースの曖昧さを明らかにします。
3. 決定論的なエントリーポイントを追加する — SKILL.mdにentryを宣言して、確実で安全な実行を行います。skill initを使用してスキャフォールドを作成し、skill validateを使用して準備状況を確認します。
4. 本番環境のエージェントでテストする — ターゲット環境でエンドツーエンドの検証を行い、その後デプロイします。

📦 インストール

Claude Desktop（ワンクリック）

インストール後、Claude Desktopの設定でスキルのパスを修正して、あなたのスキルディレクトリを指すようにしてください。

Claude Code

claude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills

Cursor

プロジェクトの.cursor/mcp.jsonに追加するか（またはSettings → MCP → Add Server）：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

手動インストール

# PyPIから（推奨）
uv pip install mcp-skill-server

# またはソースから
git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server && uv sync

# サーバーを起動
uvx mcp-skill-server serve /path/to/my/skills

その後、エディタのMCP設定に追加します：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

💻 使用例

スキルの作成

オプションA：skill initを使用する（推奨）

# 新しいスキルを作成
uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"

# またはスタンドアロンコマンドを使用
uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"

# 既存のプロンプトのみのClaudeスキルを実行可能なMCPスキルに昇格させる
uv run mcp-skill-init ./existing_claude_skill

オプションB：手動設定

1. スクリプトを含むフォルダを作成

my_skills/
└── hello/
    ├── SKILL.md
    └── hello.py

2. フロントマター付きのSKILL.mdを追加

---
name: hello
description: A friendly greeting skill
entry: uv run python hello.py
---

# Hello Skill

Greets the user by name.

3. argparseを使用してスクリプトを書く

# hello.py
import argparse

parser = argparse.ArgumentParser(description="Greeting skill")
parser.add_argument("--name", default="World", help="Name to greet")
args = parser.parse_args()

print(f"Hello, {args.name}!")

以上です。サーバーは--help出力からコマンドとパラメーターを自動的に検出します。設定は必要ありません。

デプロイのための検証

スキルが本番環境に移行する準備ができたら：

uv run mcp-skill-server validate ./my_skills/hello
# または
uv run mcp-skill-validate ./my_skills/hello

チェック内容：

• 必須のフロントマターフィールド（名前、説明、エントリー）
• エントリーコマンドが許可されたランタイムを使用していること
• スクリプトファイルが存在すること
• コマンドが--helpで検出可能であること

動作原理

MCPツール

サーバーはエージェントに4つのツールを公開します：

スキーマの検出

サーバーは--help出力を解析することで、スキルのインターフェースを自動的に検出します：

# Subcommands become separate commands
subparsers = parser.add_subparsers(dest='command')
analyze = subparsers.add_parser('analyze', help='Run analysis')

# Arguments become parameters with inferred types
analyze.add_argument('--year', type=int, required=True)  # int, required
analyze.add_argument('--file', type=str)                  # string, optional

出力ファイル

output/に保存されたファイルは自動的に検出されます。あるいは、OUTPUT_FILE:/path/to/fileを標準出力に出力してください。

プラグイン

出力ハンドラー

スキルによって生成されたファイルを処理します（アップロード、コピー、変換など）：

from mcp_skill_server.plugins import OutputHandler, LocalOutputHandler

# Default: tracks local file paths
handler = LocalOutputHandler()

# Optional GCS handler (requires `uv sync --extra gcs`)
from mcp_skill_server.plugins import GCSOutputHandler
handler = GCSOutputHandler(
    bucket_name="my-bucket",
    folder_prefix="skills/outputs/",
)

レスポンスフォーマッター

MCPツールのレスポンスで実行結果をカスタマイズします：

from mcp_skill_server.plugins import ResponseFormatter

class CustomFormatter(ResponseFormatter):
    def format_execution_result(self, result, skill, command):
        return f"Result: {result.stdout}"

# Use with create_server()
from mcp_skill_server import create_server
server = create_server(
    "/path/to/skills",
    response_formatter=CustomFormatter()
)

開発

git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server
uv sync --dev
uv run pytest
uv run mcp-skill-server serve examples/

詳細情報

• Tool Design for LLMs — なぜスキルが生のツールを公開するのではなく、リスト/取得/実行パターンを使用するのか、そしてそれがLLMの精度にどのように影響するか

📄 ライセンス

MIT