SkillMCP（スキル管理システム）

コンテナ化され水平スケーラブルなModel Context Protocol（MCP）サーバーで、AIエージェントのスキルを配布・管理するためのものです。

概要と動機

AIエージェントは、複雑なエンジニアリングタスクや分析タスクを実行するために、ドメイン固有のスキル（命令、メタデータ、スキーマ、参照アセット）に依存しています。しかし、多様なチームやエージェント群にわたってスキルを管理することは、しばしば重大な運用上の課題を引き起こします。

• 断片化・陳腐化したスキル: 散在する個別リポジトリに保存されたスキルや手動でコピーされたスキルは、すぐに同期が取れなくなり、エージェントが古い、または互換性のないワークフローを実行してしまいます。

• 配布・更新のボトルネック: 分散したエージェントインスタンス全体にスキル更新を配布するには、手動同期や脆弱なファイルコピー手順が必要です。

• バージョニングの欠如と診断の困難さ: 不変のバージョニングなしでスキルが編集されると、回帰やエージェントの動作変化の診断はほぼ不可能になります。

• 単一ホストのスケーラビリティ制限: 従来のstdioベースのMCPサーバーは単一のローカルホストプロセスに縛られており、水平スケーリングと高可用性を阻みます。

SkillMCPは、ステートレスStreamable HTTP（後方互換性のあるSSEサポート付き）を採用した集中管理型・コンテナ化・水平スケーラブルなスキル管理システムを提供することで、これらの課題を解決します。

Related MCP server: SkillShare MCP Server

主な機能と特長

1. 集中管理とバージョン管理されたスキルパッケージング

• 不変のコンテナリリース: スキル（SKILL.md、references/、examples/）は、明示的なsemver（v1.2.0）でタグ付けされたDockerイメージ内に直接パッケージ化され、100%再現可能な環境と監査可能性を保証します。

• 統合スキルリポジトリ: すべてのドメインスキルを単一の保守可能なリポジトリで管理・検証・バンドルすることで、断片化した複数リポジトリ間のドリフトを排除します。

• 迅速なトラブルシューティングとトレーサビリティ: バージョン管理されたコンテナタグにより、エージェントの問題の診断、過去の動作の再現、変更の即時ロールバックが容易になります。

2. Streamable HTTP上のステートレスMCP（水平スケーラビリティ）

• 真のステートレス要求/応答アーキテクチャ: Streamable HTTPは標準のHTTP POSTリクエストを使用し、バックエンドインスタンスはクライアント呼び出し間で長期にわたるインメモリソケット状態を保持しません。

• セッションの分離と水平スケーリング: 個々のリクエストは、スティッキーセッションを必要とせずに、Nginxリバースプロキシまたはロードバランサーの背後にある任意のバックエンドコンテナレプリカにルーティングできます。

• 短時間のストリーミング: ストリーミングを必要とする応答は、その特定のペイロードの間だけtext/event-streamにアップグレードされ、JSON-RPC応答が完了するとすぐに閉じられます。

• レガシーSSE互換性: 永続チャネルを必要とするクライアント向けに、プロキシバッファ回避（proxy_buffering off）と拡張読み取りタイムアウトを設定したレガシーServer-Sent Events（/sse）をサポートします。

• Nginx Ingressロードバランシング: least_connルーティング、keepalive接続プール、専用の/healthzヘルスチェックを設定し、ゼロダウンタイムのローリング更新を実現します。

[!WARNING] トランスポートと水平スケーラビリティ:

• Streamable HTTP（default、推奨）: 真のステートレス。セッションアフィニティなしで、レプリカ間の水平オートスケーリングと任意のロードバランシングが可能です。

• ネイティブSSE（SKILLMCP_TRANSPORT=sse）: 永続的なTCPストリーム結合によりステートフルです。ネイティブSSEモードでは、標準のラウンドロビン/リーストコネクションのロードバランサーを使用した水平スケーリングは、スティッキーセッション（例: Nginx ip_hashやクッキーアフィニティ）または単一レプリカのデプロイを使用しない限り、POST /messagesルーティングエラーを引き起こします。

3. 開発者・エージェント向けツール

• 組み込みスキルバリデータCLI: skillmcp validate ./skillsは、パッケージ化前にディレクトリ構造、YAML frontmatter、アセットリンクを自動検証します。

• 動的なディスカバリと検索:

  • MCPツール: list_skills、get_skill、search_skills、read_skill_reference、read_skill_example。

  • MCPリソース: skill://{name}は、Markdownドキュメントを直接検査するためのものです。

• デュアルCompose環境: ボリュームマウントによるホットリロードで即座にローカル開発できるdocker-compose.local.ymlと、本番デプロイ用のdocker-compose.ymlを提供します。

• TREM Python標準: uv、pydantic-settings、標準ライブラリのlogging、pytestを使用し、Testable（テスト可能）、Readable（読み取り可能）、Extensible（拡張可能）、Maintainable（保守可能）というTREM原則に厳密に従って構築されています。

• 自動化されたCI/CDパブリッシング: テストを検証し、バージョンタグ（v*.*.*）で不変のsemverリリースをDocker HubにプッシュするGitHub Actionsパイプラインを備えています。

クイックスタート

前提条件

• Python 3.11+

• uv

• Docker & Docker Compose

ローカルインストール

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

ローカルでのサーバー実行

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Dockerトポロジー

ローカル開発（ライブリロードとIngress）

docker compose -f docker-compose.local.yml up -d --build

• Nginx Ingress: http://localhost:8080（/healthzヘルスチェック）

• バックエンドアプリ: http://localhost:8000（/healthzヘルスチェック）

本番デプロイ

docker compose up -d

テストシーム

• シーム1: ドメインサービス: tests/test_domain_service.py（スキャナー、パーサー、トラバーサル安全性、クエリエンジンを検証）

• シーム2: MCPプロトコルとツール: tests/test_mcp_server.pyおよびtests/test_mcp_http.py（FastMCPツール、リソース、ASGIトランスポートルートを検証）

• シーム3: CLIと統合: tests/test_cli.py（CLIバリデータ、list、serveコマンドを検証）