Specbridge

🚀 SpecBridge

OpenAPI仕様をMCPツールに変換するMCPサーバーです。フォルダ内のOpenAPI仕様ファイルをスキャンし、自動的に対応するツールを生成します。設定ファイルや個別のサーバーは必要ありません。単に仕様ファイルをフォルダに配置するだけでツールが利用できるようになります。

TypeScript用のFastMCPを使用して構築されています。

✨ 主な機能

• 🎯 ゼロコンフィグレーション：ファイルシステムがインターフェースです。OpenAPI仕様をフォルダに配置するだけです。
• 🔐 自動認証：{API_NAME}_API_KEY パターンのシンプルな .env ファイルです。
• 🏷️ 名前空間の分離：複数のAPIがきれいに共存します（例：petstore_getPet, github_getUser）。
• 📝 完全なOpenAPIサポート：パラメータ、リクエストボディ、認証、レスポンスを処理します。
• 🚀 複数のトランスポート方式：stdioとHTTPストリーミングをサポートします。
• 🔍 組み込みのデバッグ機能：読み込まれた仕様とツールを表示する list コマンドがあります。

🚀 クイックスタート

1️⃣ インストール（オプション）

npm install -g specbridge

2️⃣ 仕様フォルダの作成

mkdir ~/mcp-apis

3️⃣ OpenAPI仕様の追加

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

# 例：Petstoreの仕様をダウンロード
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4️⃣ 認証の設定（オプション）

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

# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key

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

Claude DesktopまたはCursorの場合、MCP設定に追加します。

マシンにインストールされている場合：

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

それ以外の場合：

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

💻 使用例

基本的な使用法

# デフォルト：stdioトランスポート、カレントディレクトリ
specbridge

# カスタム仕様フォルダ
specbridge --specs ~/my-api-specs

# HTTPトランスポートモード
specbridge --transport httpStream --port 8080

高度な使用法

# すべての読み込まれた仕様とそのツールをリストする
specbridge list

# カスタムフォルダの仕様をリストする
specbridge list --specs ~/my-api-specs

🔑 認証パターン

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

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

• petstore.json → PETSTORE_API_KEY
• github-api.yaml → GITHUB_TOKEN
• my_custom_api.yml → MYCUSTOMAPI_API_KEY

🏷️ ツール名付け

ツールは以下のパターンを使用して自動的に名前が付けられます。

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

例：

• petstore_getPetById（operationIdから）
• github_get_user_repos（GET /user/repos から生成）

📁 ファイル構造

your-project/
├── api-specs/           # あなたのOpenAPI仕様フォルダ
│   ├── .env            # 認証資格情報
│   ├── petstore.json   # OpenAPI仕様ファイル
│   ├── github.yaml     # 
│   └── custom-api.yml  # 
└── mcp-config.json     # MCPクライアント設定

📄 サンプルのOpenAPI仕様

以下は、2つのツールを作成する最小限の例です。

# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com
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仕様が有効であることを確認します。

   specbridge list --specs /path/to/specs
   

2. ファイルの拡張子が正しいことを確認します（.json, .yaml, .yml）。
3. サーバーログを確認して、解析エラーがないことを確認します。

⚠️ 重要提示

Specbridgeは、--specs 引数やその他のファイルパスに絶対パス（空白なし）を使用すると最適に動作します。相対パスや空白を含むパスは、一部のプラットフォームや一部のMCPクライアントで問題を引き起こす可能性があります。

🔐 認証が機能しない場合

1. .env ファイルが仕様ディレクトリにあることを確認します。
2. 命名パターンが仕様ファイル名と一致することを確認します。
3. リストコマンドを使用して認証設定を確認します。

   specbridge list
   

🔄 仕様変更後にツールが更新されない場合

1. MCPサーバーを再起動して、仕様を再読み込みします。
2. ファイルのパーミッションを確認します。
3. 必要に応じてMCPクライアントを再起動します。

🛠️ 開発

# クローンとインストール
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# ビルド
npm run build

# ローカルでテスト
npm run dev -- --specs ./examples

🤝 コントリビューション

コントリビューションは大歓迎です！問題やプルリクエストを自由に提出してください。