MCP Bundler Service

A microservice that bundles code from GitHub repositories and prepares it for deployment. It supports direct return of bundled code or uploading to Google Cloud Storage.

Quick Start

# Install dependencies
pnpm install

# Start the development server
pnpm run dev

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

API Documentation

Interactive API documentation is available at /docs when the server is running.

Core Endpoints

Index Route

GET /

Returns a static HTML page with information about the service.

Health Check

GET /health

Returns a simple status check to verify the service is running.

V1 Bundler (Legacy)

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

Parameters:

• url (required): GitHub repository URL
• commit (optional): Specific commit hash to use (defaults to latest)
• format (optional): Output format - mjs (default) or cjs

Response:

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

V2 Bundler (with optional GCP Upload)

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

Parameters:

• url (required): GitHub repository URL
• commit (optional): Specific commit hash to use (defaults to latest)
• mcpId (optional): Unique identifier for your bundled server (auto-generated if not provided)

GCP Upload Enabled Response:

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

GCP Upload Disabled Response:

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

GCP Integration (Optional)

The V2 bundler can upload bundled code to Google Cloud Storage for use with other services, or return it directly if GCP integration is disabled.

Disabling GCP Upload

If you want to disable GCP uploads and get the bundled code directly in the response, set:

DISABLE_GCP_INTEGRATION=true

in your environment or .env file. When GCP integration is disabled:

1. The bundled code is returned directly in the API response
2. A copy of the bundled code archive is saved to the bundled directory in the project root
3. The archive filename follows the format bundle-[commit-hash].tar.gz

Setting Up GCP Credentials

If you want to use GCP uploads, you need to provide your Google Cloud Platform credentials:

Add your service account key JSON directly to the .env file:

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

This is the recommended option for development and CI/CD environments.

Required Permissions

Create a service account with Storage Admin permissions for the bucket you want to use.

Deployment

The service includes a Dockerfile for containerized deployment:

# 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 Deployment

For Google Cloud Run deployment, set the GCP_SERVICE_ACCOUNT_KEY environment variable with your service account credentials JSON.

Error Handling

All endpoints include comprehensive error responses with appropriate HTTP status codes:

• 400: Invalid input parameters
• 500: Server-side errors
• 504: Timeout errors (typically for large repositories or complex dependencies)

Features

• GitHub Integration: Bundle code directly from any public GitHub repository
• Format Options: Output in either ESM (mjs) or CommonJS (cjs) format
• Commit Pinning: Specify exact commit hashes for reproducible builds
• GCP Storage: Optional upload of bundled code to Google Cloud Storage for further deployment
• Swagger Documentation: Interactive API documentation with Swagger UI
• Error Handling: Comprehensive error reporting with appropriate status codes

Limitations

• Repository bundling has a 5-minute timeout
• Large WASM files might exceed processing limits

Environment Variables

Variable	Description	Default
GCP_SERVICE_ACCOUNT_KEY	GCP service account credentials JSON	-
DISABLE_GCP_INTEGRATION	Set to "true" to disable GCP uploads	-
SENTRY_INGEST_URL	Sentry ingest URL	-

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.