Unbundle Openapi Specs

OpenAPI MCP サーバーの分割解除

このプロジェクトでは、OpenAPI 仕様ファイルを複数のファイルに分割したり、特定のエンドポイントを新しいファイルに抽出したりするツールを備えた Model Context Protocol（MCP）サーバーを提供します。MCP クライアント（AI アシスタントなど）を使用して、OpenAPI 仕様をプログラムから操作できます。

前提条件

• Node.js（LTS バージョンを推奨。例：v18 または v20）
• npm（Node.js に付属）

使い方

Smithery 経由でインストールする

Smithery 経由で、Claude Desktop 用の Unbundle OpenAPI MCP Server を自動的にインストールするには：

npx -y @smithery/cli install @auto-browse/unbundle_openapi_mcp --client claude

このサーバーを使う最も簡単な方法は npx 経由です。グローバルインストールを行わずに、常に最新バージョンを使用できます。

npx @auto-browse/unbundle-openapi-mcp@latest

代わりに、グローバルインストールすることもできます（通常は推奨されません）。

npm install -g @auto-browse/unbundle-openapi-mcp
# Then run using: unbundle-openapi-mcp

サーバーが起動し、標準入力／出力（stdio）で MCP リクエストを待ち受けます。

クライアントの設定

VS Code、Cline、Cursor、Claude Desktop などの MCP クライアントでこのサーバーを使用するには、それぞれの設定ファイルに設定を追加してください。npx を使う方法を推奨します。

VS Code / Cline / Cursor

次の内容をユーザーの settings.json（Ctrl+Shift+P > Preferences: Open User Settings (JSON) から開けます）またはワークスペースのルートにある .vscode/mcp.json ファイルに追加してください。

// In settings.json:
"mcp.servers": {
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
},

// Or in .vscode/mcp.json (omit the top-level "mcp.servers"):
{
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
}

Claude Desktop

次の内容を claude_desktop_config.json ファイルに追加してください。

{
	"mcpServers": {
		"unbundle_openapi": {
			// You can choose any key name
			"command": "npx",
			"args": ["@auto-browse/unbundle-openapi-mcp@latest"]
		}
		// ... other servers can be added here
	}
}

設定を追加した後、変更を反映するためにクライアントアプリケーションを再起動してください。

提供される MCP ツール

split_openapi

説明： redocly split コマンドを実行し、OpenAPI 定義ファイルの構造に基づいて、複数の小さなファイルに分割します。

引数：

• apiPath（string、必須）：入力する OpenAPI 定義ファイルへの絶対パス（例：openapi.yaml）。
• outputDir（string、必須）：分割後のファイルを保存するディレクトリへの絶対パス。このディレクトリが存在しない場合は作成されます。

戻り値：

• 成功時：redocly split コマンドの標準出力を含むテキストメッセージ（通常は確認メッセージ）。
• 失敗時：コマンド実行時の標準エラーまたは例外の詳細を含むエラーメッセージ。isError: true が設定されます。

使用例（概念的な MCP リクエスト）：

{
	"tool_name": "split_openapi",
	"arguments": {
		"apiPath": "/path/to/your/openapi.yaml",
		"outputDir": "/path/to/output/directory"
	}
}

extract_openapi_endpoints

説明： 大きな OpenAPI 定義ファイルから特定のエンドポイントを抽出し、それらのエンドポイントと参照先のコンポーネントのみを含む、新しく小さな OpenAPI ファイルを作成します。元のファイルを分割し、指定されたパスのみを残すように構造を変更してから、結果をバンドルします。

引数：

• inputApiPath（string、必須）：入力する大きな OpenAPI 定義ファイルの絶対パスです。
• endpointsToKeep（文字列の配列、必須）：最終出力に含める正確なエンドポイントパス（文字列）のリストです（例：["/api", "/api/projects/{id}{.format}"]）。元の仕様に存在しないパスは無視されます。
• outputApiPath（string、必須）：バンドル後の小さな OpenAPI ファイルを保存する絶対パスです。ディレクトリが存在しない場合は作成されます。

戻り値：

• 成功時：作成したファイルのパスと、redocly bundle コマンドの標準出力を示すテキストメッセージです。
• 失敗時：失敗した処理（分割、変更、バンドル）の詳細を含むエラーメッセージです。isError: true が設定されます。

使用例（概念上の MCP リクエスト）：

{
	"tool_name": "extract_openapi_endpoints",
	"arguments": {
		"inputApiPath": "/path/to/large-openapi.yaml",
		"endpointsToKeep": ["/users", "/users/{userId}/profile"],
		"outputApiPath": "/path/to/extracted-openapi.yaml"
	}
}

注： このサーバーは、内部で npx @redocly/cli@latest を使用して、基盤となる split コマンドと bundle コマンドを実行します。@redocly/cli がキャッシュされていない場合、npx による取得にインターネット接続が必要になることがあります。extract_openapi_endpoints の処理中に一時ファイルが作成され、自動的に削除されます。

開発

貢献する場合、またはソースからサーバーを実行する場合：

1. クローン： このリポジトリをクローンします。
2. 移動： cd unbundle_openapi_mcp
3. 依存関係のインストール： npm install
4. ビルド： npm run build（TypeScript を dist/ にコンパイルします）
5. 実行： npm start（dist/ 内のコンパイル済みコードを使用してサーバーを起動します）