skill2mcp

skill2mcpは、SKILL.mdドキュメントをMCP対応のツール定義に変換し、単一のファイルまたはスキルディレクトリ全体から最小限のデプロイ可能なMCPサーバーパッケージを生成するTypeScript CLI/ライブラリです。

生成されたサーバーは公式のMCP TypeScript SDK (@modelcontextprotocol/sdk) を使用し、stdio、http、またはboth（両方）のトランスポートをサポートしています。

このプロジェクトの目的

SKILLドキュメントは通常、半構造化されたマークダウン（フロントマター + 本文 + テーブル）です。MCPツールには厳密なコントラクト（name、description、inputSchema）が必要です。

skill2mcpは、以下の階層化されたパイプラインでそのギャップを埋めます：

1. マークダウンを安定した中間表現（IR）に解析する

2. IRをMCPツール定義に変換する

3. ハンドラスタブを含むデプロイ可能なMCPサーバーパッケージを生成する

Related MCP server: Skillz

現在のステータス

MVP（実用最小限の製品）が実装され、動作しています：

• 決定論的パーサー (strict, tolerant)

• 不足しているメタデータのフォールバック用カスケードセマンティックモード (semantic)

• ツール変換 (SchemaBuilder, ToolMapper, ToolValidator)

• MCPスタイルのツールJSONを出力する inspect コマンド

• デプロイ可能なMCPサーバーパッケージを出力する build コマンド

• 生成されたサーバーは stdio + http をサポート

• 反復的な再生成のための build --watch

インストール

要件

• Node.js 20以上

• npm 10以上

ローカルインストール

npm install

CLIのビルド

npm run build

クイックスタート

1. 単一のSKILLを解析する

npm run parse -- ./fixtures/skills/valid-skill.md --mode strict

2. 生成されたツール定義を検査する

npm run inspect -- ./fixtures/skills --mode tolerant

3. デプロイ可能なMCPサーバーパッケージを生成する

npm run gen -- ./fixtures/skills --out ./generated/mcp-server --transport both --mode tolerant

4. 生成されたサーバーを実行する

cd ./generated/mcp-server
npm install
npm run build
npm run start:stdio
# or
npm run start:http

HTTPエンドポイント:

POST /mcp

CLIリファレンス

parse

SKILLマークダウンをIR JSONに変換します。

skill2mcp parse <input> [--mode strict|tolerant|semantic]

引数:

• <input>: .mdファイルまたはディレクトリへのパス

オプション:

• --mode: パーサーモード（デフォルトは tolerant）

• --format: 現在は json

出力:

• 解析された SkillDocument を含む results[]

• ソースファイルごとの diagnostics[]

inspect

解析されたIRをMCPライクなツール定義に変換します。

skill2mcp inspect <input> [--mode strict|tolerant|semantic]

出力:

• tools[]: 生成されたツール定義 (name, description, inputSchema)

• results[]: ソースごとのツール + 診断情報

build

1つまたは複数のスキルからデプロイ可能なMCPサーバーパッケージを生成します。

skill2mcp build <input> --out <dir> [--transport stdio|http|both] [--mode strict|tolerant|semantic] [--watch]

引数:

• <input>: .mdファイルまたはディレクトリへのパス

必須オプション:

• --out: 生成されたパッケージの出力ディレクトリ

オプション:

• --transport: デフォルトの生成サーバートランスポート（デフォルトは both）

• --mode: 解析モード（デフォルトは tolerant）

• --watch: ソース変更時にパッケージを再生成する

出力:

• 生成されたパッケージファイル (package.json, tools.json, src/server.ts, ハンドラ)

• JSON形式の診断サマリー

解析モード

strict

• 必須のメタデータ/スキーマが不足している場合に失敗します

• CIの品質ゲートに最適です

tolerant

• フィールドが不足していても警告を出して続行します

• 品質の混在するスキルをバッチ処理するのに最適です

semantic

• tolerant解析から開始します

• OpenRouter（設定時）を通じてセマンティック抽出を試みます

• 未解決のフィールドに対して決定論的なフォールバック推論を適用します

• 診断トレース (SEMANTIC_* コード) を保持します

semantic モードのためのOpenRouter設定

環境変数:

• OPENROUTER_API_KEY: リモートセマンティック抽出を有効にします

• OPENROUTER_MODEL (オプション): デフォルトは anthropic/claude-3.5-sonnet

• SKILL2MCP_CACHE_DIR (オプション): キャッシュディレクトリを上書きします

• OPENROUTER_HTTP_REFERER (オプション): OpenRouterヘッダーとして転送されます

• OPENROUTER_X_TITLE (オプション): OpenRouterヘッダーとして転送されます

キャッシュの動作:

• セマンティック応答はコンテンツハッシュによって .skill2mcp-cache/semantic-openrouter-cache.json にキャッシュされます

• キャッシュが存在する場合、セマンティックモードはキャッシュを再利用し、余分なリモート呼び出しを回避します

標準的な SKILL.md フォーマット（推奨）

---
name: docx-generator
version: 1.0.0
description: Generate Word docs from structured markdown
tags: [documents, office]
---

## Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| content | string | yes |  | Markdown content |
| title | string | yes |  | Document title |

## Examples
**Input:** `{ content: "# Hello", title: "Report" }`
**Output:** report.docx generated at /outputs/

## Triggers
- "generate document"
- "create report"

生成されるパッケージ構造

generated/mcp-server/
  package.json
  tsconfig.json
  README.md
  tools.json
  src/
    server.ts
    generated-tools.ts
    handlers/
      index.ts
      <tool_name>.ts

開発

スクリプト

npm run build       # compile TypeScript
npm run test        # run test suite
npm run parse       # parse command entry
npm run inspect     # inspect command entry
npm run gen         # build command entry

テストスイート

現在の自動化されたカバレッジには以下が含まれます:

• パーサーの動作 (strict, tolerant, semantic)

• スキーマビルダーとツールマッピング

• inspectコマンドの出力コントラクト

• エンドツーエンドのビルド成果物生成

エンジニアリングの慣習

• AGENTS.md のリポジトリコラボレーションルールに従うこと

• 製品/ビジネスの指示は ROADMAP.md に準拠すること

• AIが生成したコミットメッセージには [AI] プレフィックスを使用すること

リリース成果物

このリポジトリには以下が含まれます:

• デュアルライセンス配布: MIT OR Apache-2.0

• CHANGELOG.md

• CONTRIBUTING.md

• RELEASE_CHECKLIST.md

コラボレーションモデル

• ガバナンスと決定ルール: GOVERNANCE.md

• 行動規範: CODE_OF_CONDUCT.md

• セキュリティ報告: SECURITY.md

• サポートチャンネル: SUPPORT.md

既知の制限事項

• パラメータ解析は現在 ## Parameters 内のマークダウンテーブル形式を前提としています

• セマンティックモードは不足しているメタデータを優先し、抽出が可能な場合は不足しているパラメータを補完する可能性があります

• ウォッチモードは現在のツリーを追跡します。後から深くネストされたフォルダが追加された場合は、完全にカバーするためにウォッチを再起動してください

ロードマップの整合性

アクティブな実装は ROADMAP.md の段階的な配信に従います。

GenAI統合ポリシー（有効時）は、ロードマップの指示で定義されている通り、デフォルトのプロバイダ戦略としてOpenRouterを優先します。

ライセンス

以下いずれかのライセンスの下でライセンスされています:

• MIT License (LICENSE-MIT)

• Apache License 2.0 (LICENSE-APACHE)

ご自身の選択によります。