MCP Bundler Service

MCP Bundler Service

GitHub リポジトリのコードをバンドルし、デプロイ用に準備するマイクロサービスです。バンドルしたコードを直接返す方法と、Google Cloud Storage にアップロードする方法に対応しています。

クイックスタート

# Install dependencies
pnpm install

# Start the development server
pnpm run dev

# Access the API documentation
open http://localhost:8080/docs

API ドキュメント

サーバーの実行中は、/docs でインタラクティブな API ドキュメントを利用できます。

主なエンドポイント

インデックスルート

GET /

サービスの情報を含む静的 HTML ページを返します。

ヘルスチェック

GET /health

サービスが実行中であることを確認するための簡単なステータスチェックを返します。

V1 バンドラー（レガシー）

GET /bundler?url=<github_url>&commit=<commit_hash>&format=<mjs|cjs>

パラメーター：

• url（必須）：GitHub リポジトリの URL
• commit（任意）：使用する特定のコミットハッシュ（デフォルトは最新）
• format（任意）：出力形式 — mjs（デフォルト）または cjs

レスポンス：

{
  "data": "<bundled code as string>"
}

V2 バンドラー（GCP へのアップロードは任意）

GET /v2/bundler?url=<github_url>&commit=<commit_hash>&mcpId=<your_mcp_id>

パラメーター：

• url（必須）：GitHub リポジトリの URL
• commit（任意）：使用する特定のコミットハッシュ（デフォルトは最新）
• mcpId（任意）：バンドルしたサーバーの一意の識別子（指定しない場合は自動生成）

GCP アップロードが有効な場合のレスポンス：

{
  "success": true,
  "gcp_upload": {
    "bucket": "your-bucket-name",
    "path": "your-mcp-id/commit-hash/",
    "files": [
      "bundle-commit-hash.tar.gz"
    ]
  }
}

GCP アップロードが無効な場合のレスポンス：

{
  "success": true,
  "data": "<bundled code as string>"
}

GCP 連携（任意）

V2 バンドラーは、他のサービスで使用するためにバンドルしたコードを Google Cloud Storage にアップロードできます。GCP 連携が無効な場合は、コードを直接返します。

GCP アップロードを無効にする

GCP へのアップロードを無効にし、レスポンスでバンドルしたコードを直接取得するには、次の値を設定します。

DISABLE_GCP_INTEGRATION=true

環境変数または .env ファイルに設定してください。GCP 連携が無効な場合：

1. バンドルしたコードが API レスポンスで直接返されます
2. バンドルしたコードのアーカイブのコピーが、プロジェクトルートの bundled ディレクトリに保存されます
3. アーカイブのファイル名は bundle-[commit-hash].tar.gz 形式になります

GCP 認証情報の設定

GCP へのアップロードを使用するには、Google Cloud Platform の認証情報を指定する必要があります。

サービスアカウントキーの JSON を .env ファイルに直接追加します。

GCP_SERVICE_ACCOUNT_KEY={"type": "service_account", "project_id": "your-project-id", ...}

これは、開発環境および CI/CD 環境で推奨される方法です。

必要な権限

使用するバケットに対して Storage Admin 権限を持つサービスアカウントを作成してください。

デプロイ

このサービスには、コンテナ化してデプロイするための Dockerfile が含まれています。

# Build the Docker image
docker build -t mcp-bundler .

# Run the container
docker run -p 8080:8080 -e GCP_SERVICE_ACCOUNT_KEY='{"type":"service_account",...}' mcp-bundler

Cloud Run へのデプロイ

Google Cloud Run にデプロイする場合は、サービスアカウント認証情報の JSON を GCP_SERVICE_ACCOUNT_KEY 環境変数に設定してください。

エラー処理

すべてのエンドポイントは、適切な HTTP ステータスコードを含む包括的なエラーレスポンスを返します。

• 400：入力パラメーターが無効です
• 500：サーバー側のエラーです
• 504：タイムアウトエラーです（通常、大規模なリポジトリや複雑な依存関係で発生します）

機能

• GitHub 連携：任意の公開 GitHub リポジトリからコードを直接バンドル
• 形式の選択肢：ESM（mjs）または CommonJS（cjs）形式で出力
• コミットの固定：再現可能なビルドのため、正確なコミットハッシュを指定
• GCP ストレージ：後続のデプロイ用に、バンドルしたコードを Google Cloud Storage にアップロード（任意）
• Swagger ドキュメント：Swagger UI によるインタラクティブな API ドキュメント
• エラー処理：適切なステータスコードを含む包括的なエラー報告

制限事項

• リポジトリのバンドル処理は5分でタイムアウトします
• 大きな WASM ファイルは処理上限を超える可能性があります

環境変数

変数	説明	デフォルト
GCP_SERVICE_ACCOUNT_KEY	GCP サービスアカウント認証情報の JSON	-
DISABLE_GCP_INTEGRATION	GCP へのアップロードを無効にするには "true" を設定	-
SENTRY_INGEST_URL	Sentry の取り込み URL	-

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。