SpecBridge MCP

SpecBridge MCPは、OpenAPI/Humaのコントラクト情報をAIエージェントに提供するための**「クローン＆オウン」型MCPスターター**です。OpenAPI/Huma仕様を、フロントエンドやクライアントコードを変更する前にエージェントが利用できる、決定論的なエンドポイントメタデータ、スキーマ、検証ファクト、参照DTO、TypeScript宣言に変換します。

このプロジェクトはnpm公開ではなく、リポジトリを直接利用することを前提としています。クローンして、バックエンドレジストリを自身のプライベートまたはパブリックな仕様に合わせて調整し、ローカルのMCPサーバーをエージェントホストに登録してください。実装は、ダウンストリームでのファイル変更を避け、中立的なパブリックデモバックエンドを使用し、複数のバックエンド注入をサポートし、推論されたヘルパーを保証ではなくベストエフォートとして扱うことで、コアの非依存性を維持しています。

ステータス: 実験的。ツールとしての有用性はローカル自動化において高いですが、リポジトリは各チームが所有し、適応させることを目的としています。

簡略な歴史

SpecBridge MCPは、バックエンドAPIコントラクト周辺の開発サイクルを改善するために、SesameLabの社内ツールとして始まりました。実際に、MCPを通じてAIエージェントに構造化されたOpenAPI/Humaコントラクトデータを提供することで、APIドキュメントページを直接読み込ませる場合と比較して、ハルシネーションが減少しました。

提供機能

• 1つまたは複数のOpenAPI/Huma互換仕様に対応した設定可能なバックエンドレジストリ

• 実際のパブリックOpenAPI URLを使用したゼロコンフィグのデモバックエンド

• JSON/YAMLサポートを備えた仕様の読み込みと更新

• エンドポイントのリスト表示とフィルタリング

• 決定論的なファクトを含むエンドポイントコントラクトバンドル:

  • 操作メタデータ

  • パラメータ

  • リクエストおよびレスポンススキーマ

  • 参照コンポーネントスキーマ

  • エンドポイントスコープのTypeScript DTO宣言

  • required、nullable、enum、format、配列、マップ、合成などの検証ファクト

• コンポーネントスキーマからのTypeScript DTO宣言生成

• 決定論的な仕様ファクトを優先するベストエフォート型の提案ヘルパー

非目標

• v1に向けたnpmへのプロジェクト公開

• 汎用的なインストール可能なCLI抽象化の提供

• ダウンストリームのフロントエンド/クライアントリポジトリの変更

• フレームワーク固有のクライアントやSDKジェネレーターになること

• 仕様のホスティングやチームのAPIデータの遠隔保存

要件

• Node.js 18+

• pnpm 10+

インストール

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

バックエンドの設定

SpecBridgeには、ツールがすぐに動作するようにパブリックデモAPIを指す openapi.backends.json が同梱されています。

独自のAPIを使用するには、openapi.backends.json を編集するか、OPENAPI_BACKENDS_FILE に別のJSONファイルを指定してください。

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

設定の優先順位

ツール呼び出しにおいて、明示的な specUrl のオーバーライドが最初に試行されます。

バックエンドレジストリのソースは以下の順序でマージされ、後のソースが id によって前のソースを上書きします:

1. 組み込みのパブリックデモバックエンド

2. リポジトリローカルの openapi.backends.json (存在する場合)

3. OPENAPI_BACKENDS_FILE (設定されている場合)

4. OPENAPI_BACKENDS (設定されている場合)

DEFAULT_BACKEND_ID はデフォルトのバックエンドを選択します。設定されていない場合、SpecBridgeは swagger-petstore を使用します。

環境変数

• MCP_TRANSPORT: stdio または http

• MCP_HTTP_HOST: HTTPバインドホスト

• MCP_HTTP_PORT: HTTPポート

• MCP_HTTP_PATH: /mcp などのMCPエンドポイントパス

• MCP_HTTP_STATELESS: ステートレスHTTPモードの場合は true に設定

• DEFAULT_BACKEND_ID: デフォルトのバックエンドID

• OPENAPI_BACKENDS: バックエンド設定のJSON配列

• OPENAPI_BACKENDS_FILE: バックエンド設定JSONファイルへのパス

• OPENAPI_FETCH_TIMEOUT_MS: 仕様読み込みのフェッチタイムアウト

• OPENAPI_CACHE_TTL_MS: インメモリ仕様キャッシュのTTL

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: 静的Swagger UIスクリプトからの厳密なJSONオブジェクト抽出を有効化（取得したJavaScriptは実行されません）

実行

stdioモード

pnpm mcp
# or
./mcp-server.sh

HTTPモード

pnpm mcp:http

ステートレスHTTPモード:

pnpm mcp:http:stateless

MCPホストの設定

コマンドベースのstdio設定

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Codex config.toml の例

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP URL

サーバーを起動します:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

次に、ホストを以下に接続します:

• http://127.0.0.1:3000/mcp

ホストでセッション状態に問題がある場合は、--stateless を付けて再試行してください。

ツール

推奨フロー:

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

設定されたバックエンドターゲット、デフォルトのバックエンドID、およびオプションのドメインヒントをリスト表示します。

load_openapi_spec

バックエンドのOpenAPI/Huma互換仕様を読み込むか更新します。直接の specUrl オーバーライドをサポートしています。

list_api_endpoints

読み込まれた仕様から、タグ、メソッド、パスのサブ文字列、制限フィルターを使用してエンドポイントをリスト表示します。

get_endpoint_contract

決定論的なエンドポイントコントラクトバンドルを返します: 操作メタデータ、パラメータ、リクエストボディ、レスポンス、参照スキーマ、エンドポイントスコープのTypeScript DTO宣言、検証ファクト、およびベストエフォート型のヒント。

generate_typescript_dto

コンポーネントスキーマ名からTypeScript DTO宣言を生成し、参照されているネストされたDTO型を含めます。

propose_new_endpoint

現在の仕様で見つかったパターンに沿った、ベストエフォート型のエンドポイントとDTOの提案を返します。これは決定論的な保証ではなく、エージェントの補助として扱ってください。

開発

pnpm install
pnpm check
pnpm build
pnpm test

便利なスクリプト:

• pnpm check: Biomeチェック

• pnpm format: Biomeフォーマットの適用

• pnpm lint: Biomeリンターのみ

• pnpm build: TypeScriptビルドのクリーンアップ

• pnpm test: 全テストのビルドと実行

• pnpm test:e2e: MCPスモークテストのビルドと実行

クローン＆オウンのガイダンス

SpecBridgeは意図的にリポジトリファーストです。コアを小さく保ち、バックエンド設定をローカルで適応させ、クライアントコードの編集方法はダウンストリームのエージェントに任せてください。チームがカスタム認証、内部命名規則、または追加のコントラクトファクトを必要とする場合は、グローバルなパッケージ抽象化と戦うのではなく、クローン内でそれらを追加してください。