mcp-skill-server

ほとんどのコーディングアシスタントは、すでにスキルをネイティブにサポートしているため、スキルの検出だけを目的とした MCP サーバーは必要ありません。このパッケージが価値を発揮するのは、スキルの実行を決定論的かつデプロイ可能にする点です。固定のエントリーポイントと制御された実行により、エディターで開発したスキルを、サンドボックス化されていない本番環境で実行できます。また、段階的な読み込みにも対応しているため、エージェントはすべてをあらかじめ読み込むのではなく、必要に応じてスキルを検出できます。

---

MCP Skill Server

普段の作業場所でエージェントスキルを構築できます。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/coding agent skill                → SKILL.md + scripts, but no fixed entry — agent decides how to run them
2. Local MCP skill (+ entry)   → Fixed entry point, schema from --help, usable daily via this server
3. Production                  → Same skill, same entry — deployed to your enterprise MCP server

ローカルで磨き、本番環境に向けて堅牢化する

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 に追加します（または「設定」→「MCP」→「サーバーを追加」を選択します）。

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

手動インストール

# From PyPI (recommended)
uv pip install mcp-skill-server

# Or from source
git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server && uv sync

# Run the server
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 を使用する（推奨）

# Create a new skill
uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"

# Or use the standalone command
uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"

# Promote an existing prompt-only Claude skill to a runnable MCP skill
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
# or
uv run mcp-skill-validate ./my_skills/hello

チェック項目：

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

仕組み

MCP ツール

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

ツール	説明
list_skills	利用可能なすべてのスキルを一覧表示する
get_skill	スキルの詳細（コマンド、パラメーター）を取得する
run_skill	パラメーターを指定してスキルを実行する
refresh_skills	変更後にスキルを再読み込みする

スキーマの検出

サーバーは --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/

さらに詳しく

• LLM 向けツール設計 — スキルが生のツールを公開するのではなく、list/get/run パターンを使用する理由と、それが LLM の精度に与える影響

ライセンス

MIT