specrun

SpecRun

OpenAPI 仕様を MCP ツールに変換する MCP サーバーです。フォルダー内の OpenAPI 仕様ファイルをスキャンし、対応するツールを自動生成します。生成されたツールは、任意の MCP クライアントで使用して、仕様で定義された API とやり取りできます。シンプルな `.env` ファイルを使った認証とサーバー URL 管理にも標準で対応しています。

TypeScript 用の FastMCP で構築されています。

✨ 特長

• 設定不要：ファイルシステムがインターフェースです。OpenAPI 仕様をフォルダーに配置するだけです
• OpenAPI 3.0 と 2.0 に対応：OpenAPI 3.x と Swagger 2.0 の両方の仕様で動作します
• 名前空間の分離：複数の API をすっきり共存させられます
• OpenAPI を全面的にサポート：パラメーター、リクエストボディ、認証、レスポンスを処理します
• 任意のツールを実行して API とやり取り：たとえば、cars_addCar で cars.json 仕様の POST /cars を呼び出して新しい車を作成したり、github_get_user_repos で github.yaml 仕様の GET /user/repos を呼び出してリポジトリを一覧表示したりできます。
• 任意のツールをカスタム入力で実行：パラメーターやリクエストボディに構造化された JSON 入力を渡せます
• 任意のツールを実行して仕様の詳細を確認：パラメーター、リクエストボディのスキーマ、レスポンスのスキーマなど、任意のツールの元の OpenAPI 仕様の詳細を取得できます
• 任意のツールを実行して API レスポンスをリソースとして取得：各ツール呼び出しは、リクエスト URL、リクエストボディ、レスポンスを含む JSON リソースを返します
• 任意のツールをバッチ実行：specrun_batch ツールで複数の入力を使って任意のツールを実行し、統合された JSON リソースを返します
• 自動認証：{API_NAME}_API_KEY パターンを使用したシンプルな .env ファイル
• .env のプレースホルダーを自動追加：不足している場合に {API_NAME}_SERVER_URL と {API_NAME}_BEARER_TOKEN のエントリーを追加します
• 複数のトランスポート：stdio と HTTP ストリーミングに対応
• デバッグ機能を標準搭載：一覧表示コマンドで読み込まれた仕様とツールを確認できます
• MCP プロンプト：ツールの一覧表示、入力の生成、スキーマの説明に使えるプロンプトを標準搭載
• エージェント：SpecRun ツールを使って API をガイドに沿って調査・操作するよう設定されたエージェント（.github/agents/specrun.agent.md）

クイックスタート

必要条件

• Node.js 22 以降

1️⃣ インストール（任意）

npm install -g specrun

2️⃣ サーバーが OpenAPI 仕様ファイルを読み込める場所に仕様フォルダーを作成します。例：

mkdir ~/specs

3️⃣ OpenAPI 仕様を追加

任意の .json、.yaml、または .yml の OpenAPI 仕様ファイルを仕様フォルダーに配置します

4️⃣ 認証を設定（任意）

仕様フォルダーに .env ファイルを作成します：

# ~/specs/.env
CARS_API_KEY=your_api_key_here

SpecRun は各仕様に対して {API_NAME}_SERVER_URL と {API_NAME}_BEARER_TOKEN のエントリーが存在することも確認し、不足している場合は空のプレースホルダーを追加します。 {API_NAME}_SERVER_URL に値が設定されている場合、SpecRun は読み込み時に仕様ファイルを更新します：

• OpenAPI 3.0：最初の servers エントリーを更新します。
• OpenAPI 2.0（旧 Swagger 2.0）：host、schemes、basePath を更新します（OpenAPI 2.0 には servers セクションがありません）。

また、SpecRun は .env ファイルを監視し、変更後にサーバー URL と認証設定を自動的に更新します。

5️⃣ MCP クライアントの設定に追加

MCP の設定に追加します：

マシンにインストール済みの場合：

{
  "mcpServers": {
    "specrun": {
      "command": "specrun",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

それ以外の場合：

{
  "mcpServers": {
    "specrun": {
      "command": "npx",
      "args": ["-y", "specrun", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}

または、特定の Node バージョンを指定する場合：

{
  "mcpServers": {
    "specrun": {
      "command": "/Users/YOUR_USER_NAME/.local/bin/mcp-npx-node22",
      "args": ["specrun@latest", "--specs", "/absolute/path/to/your/specs"],
      "type": "stdio"
    }
  }
}

mcp-npx-node22 スクリプトファイルは nvm を使用して Node.js 22.14.0 で specrun を実行するため、システムのデフォルトの Node バージョンにかかわらず互換性が確保されます。：

#!/bin/bash
# Set the PATH to include NVM's Node.js v22.14.0 installation
export PATH="/Users/YOUR_USER_NAME/.nvm/versions/node/v22.14.0/bin:$PATH"

# Execute npx with all passed arguments
exec npx "$@"

💻 CLI の使い方

🚀 サーバーを起動

# Default: stdio transport, current directory
specrun

# Custom specs folder
specrun --specs ~/specs

# HTTP transport mode
specrun --transport httpStream --port 8080

npx で Node 22 を使って実行

デフォルトの node が 22 より古い場合は、Node 22 で SpecRun を直接実行します：

• npx -y node@22 ... は Node.js ランタイムを実行するため、次の引数にはスクリプトのパス（例：./node_modules/.bin/specrun）を指定する必要があります。
• specrun@latest は npm パッケージ指定子であり、現在の Node バージョンが SpecRun の要件を満たしている場合に限り、npx で直接使用できます。

# Or list tools
npx -y node@22 ./node_modules/.bin/specrun list --specs ~/specs

# If your default Node is already 22+, this also works
npx -y specrun@latest --specs ~/specs

📋 読み込まれた仕様とツールを一覧表示

# List all loaded specifications and their tools
specrun list

# List specs from custom folder
specrun list --specs ~/specs

🔑 認証パターン

サーバーは、次のパターンを使用して環境変数から認証を自動的に検出します。

パターン	認証タイプ	用途
{API_NAME}_API_KEY	🗝️ API キー	X-API-Key ヘッダー
{API_NAME}_TOKEN	🎫 ベアラートークン	Authorization: Bearer {token}
{API_NAME}_BEARER_TOKEN	🎫 ベアラートークン	Authorization: Bearer {token}
{API_NAME}_USERNAME + {API_NAME}_PASSWORD	👤 ベーシック認証	Authorization: Basic {base64}

SpecRun は、次の項目の .env プレースホルダーも作成します。

パターン	用途
{API_NAME}_SERVER_URL	API のベース URL
{API_NAME}_BEARER_TOKEN	トークンがない場合のプレースホルダー

{API_NAME}_SERVER_URL が設定されている場合、SpecRun はツールを生成する前に、その値を仕様に書き込みます。

• OpenAPI 3.0：最初の servers エントリを書き込みます。
• OpenAPI 2.0（旧称 Swagger 2.0）：host、schemes、basePath を書き込みます。

.env の更新は、MCP サーバーを再起動せずに自動的に適用されます。

{API_NAME} は OpenAPI 仕様のファイル名から導出されます。

• cars.json → CARS_API_KEY
• github-api.yaml → GITHUB_TOKEN
• my_custom_api.yml → MY_CUSTOM_API_KEY

🏷️ ツールの命名

ツールは、次のパターンを使用して自動的に命名されます。

• operationId がある場合：{operation_id}
• operationId がない場合：{method}_{path_segments}

名前の正規化ルール：

• snake_case に変換
• 小文字に変換
• 英数字以外の文字を _ に正規化
• 52 文字を超える場合は末尾を切り詰めます。（VS Code/Copilot との互換性を保つため、実用上の内部上限である 64 文字以内に収まります。）
• 衝突を解決する必要がある場合に限り、短いサフィックスを追加します

仕様：

• get_car_by_id（operationId から生成）
• get_user_repos（GET /user/repos から生成）

共有バッチツールを使用すると、入力の配列を指定して任意のツールを実行できます。

{
  "toolName": "cars_getCarById",
  "items": [{ "id": "123" }, { "id": "456" }],
  "failFast": false
}

バッチ応答は、各項目の出力を含む統合 JSON リソースを返します。

200 項目を超えるバッチでは、SpecRun による明示的な確認が必要です。これは、パフォーマンスの問題や意図しない結果を引き起こす可能性がある、大規模な実行を誤って行わないようにするためです。サーバーは確認を求めるメッセージを返します。続行するには、confirmLargeBatch: true と指定された confirmLargeBatchToken を指定して再試行してください。

📦 リソース出力

ツールの応答は、application/json コンテンツを持つ MCP リソースとして返されます。各リソースには次の項目が含まれます。

1. リクエスト URL
2. リクエスト本文
3. 応答ステータスと本文

リソースペイロードの例：

{
  "requestUrl": "https://api.example.com/v1/users/123",
  "requestBody": null,
  "response": {
    "status": 200,
    "body": {
      "id": "123",
      "name": "Jane Doe"
    }
  }
}

バッチ実行では、すべての項目の結果を含む単一の統合リソースが返されます。

📁 ファイル構成

your-project/
── specs/           # Your OpenAPI specs folder
   ├── .env            # Authentication credentials
   └── custom-api.yml  # Your OpenAPI spec files

🧭 MCP プロンプト

SpecRun は、一般的なワークフロー向けの MCP プロンプトを公開します。

例を含む詳細なプロンプトガイド：PROMPTS_README.md

• list_apis：読み込まれた API／ツールを一覧表示し、ユーザーにエンドポイントの選択を求めます
• generate_api_call：ツールですぐに実行できる JSON 入力ペイロードを生成します
• explain_api_schema：パラメーターとリクエスト本文のスキーマを例とともに説明します
• generate_random_data：ツールですぐに実行できるランダムな JSON ペイロードのサンプルを生成します

📄 OpenAPI 仕様の例

2 つのツールを作成する最小限の例を示します。

# ~/specs/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api-server.placeholder
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        "201":
          description: User created

次の名前のツールが作成されます。

• example_getUser
• example_createUser

🔧 トラブルシューティング

❌ ツールが表示されませんか？

1. OpenAPI 仕様が有効であることを確認してください：

   specrun list --specs /path/to/specs
   

2. ファイルの拡張子が正しいことを確認してください（.json、.yaml、.yml）。

3. サーバーログで解析エラーを確認してください。

⚠️ Note: --specs 引数やその他のファイルパスには、絶対パス（スペースを含まないもの）を使用することをおすすめします。相対パスやスペースを含むパスは、一部のプラットフォームや MCP クライアントで問題を引き起こす場合があります。

🔐 認証が機能しませんか？

1. .env ファイルが仕様ディレクトリにあることを確認してください。

2. 命名パターンが仕様ファイル名と一致していることを確認してください。

3. list コマンドを使用して、認証設定を確認してください。

   specrun list
   

🔄 仕様を変更してもツールが更新されませんか？

1. 仕様を再読み込みするため、MCP サーバーを再起動してください。
2. ファイルのアクセス許可を確認してください。
3. 必要に応じて、MCP クライアントを再起動してください。

🛠️ 開発

# Clone and install
git clone [email protected]:Pavel-Piha/specrun.git
cd specrun
npm install

# Build
npm run build

npm run dev -- list --specs ./specs

🤝 貢献

貢献を歓迎します！お気軽にイシューやプルリクエストを送信してください。