Merge pull request #2 from elizaOS/feat/x402-integration

feat(x402): optional x402 payment middleware for HTTP/SSE transports

Author: wtfsayo

.github/workflows/test.yml

@@ -11,43 +11,38 @@ jobs:
     name: E2E Tests
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x, 22.x]
-    
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
 
-    - name: Setup Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v1
       with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
+        bun-version: 'latest'
 
     - name: Install dependencies
-      run: npm ci
+      run: bun install --frozen-lockfile
 
     - name: Type check
-      run: npm run type-check
+      run: bun run type-check
 
     - name: Build project
-      run: npm run build
+      run: bun run build
 
     - name: Run E2E tests
-      run: npm run test:quick
+      run: bun run test:quick
 
     - name: Test configuration loading
       run: |
         echo "Testing basic configuration..."
-        timeout 10s node build/index.js --config=tests/configs/basic.yaml || true
+        timeout 10s bun build/index.js --config=tests/configs/basic.yaml || true
         echo "Testing JSON configuration..."
-        timeout 10s node build/index.js --config=tests/configs/basic.json || true
+        timeout 10s bun build/index.js --config=tests/configs/basic.json || true
         
     - name: Test environment configuration
       run: |
         echo "Testing environment variables..."
-        timeout 10s env MCP_SERVERS="test:npx:user-review-mcp" node build/index.js || true
+        timeout 10s env MCP_SERVERS="test:npx:user-review-mcp" bun build/index.js || true
 
   build-check:
     name: Build Verification
@@ -57,17 +52,16 @@ jobs:
     - name: Checkout repository
       uses: actions/checkout@v4
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v1
       with:
-        node-version: '20.x'
-        cache: 'npm'
+        bun-version: 'latest'
 
     - name: Install dependencies
-      run: npm ci
+      run: bun install --frozen-lockfile
 
     - name: Build project
-      run: npm run build
+      run: bun run build
 
     - name: Verify build artifacts
       run: |
@@ -76,9 +70,3 @@ jobs:
         [ -f "build/aggregator-server.js" ] || { echo "Missing aggregator-server.js"; exit 1; }
         [ -f "build/config.js" ] || { echo "Missing config.js"; exit 1; }
         echo "All build artifacts present ✅"
-        
-    - name: Test package installation
-      run: |
-        npm pack
-        npm install -g ./mcp-gateway-*.tgz
-        echo "Package installation successful ✅"

README.md

@@ -234,6 +234,26 @@ npm run test:quick  # Fast, essential tests only
 npm run test        # Full test suite (slower but comprehensive)
 ```
 
+## 🔐 Environment Variables
+
+When using x402 payment middleware or certain MCP servers, you'll need to set environment variables:
+
+```bash
+# Copy the example environment file
+cp env.example .env
+
+# Edit .env and add your keys:
+# - CONTEXT7_API_KEY: Get from https://context7.com/dashboard
+# - X402_EVM_PRIVATE_KEY: Your EVM wallet private key for payments
+# - X402_TEST_PRIVATE_KEY: Test wallet key (for testing only)
+# - TEST_PRIVATE_KEY: Additional test key for unit tests
+```
+
+**Security Notes:**
+- Never commit `.env` files or actual private keys to version control
+- Use environment variables or secure key management systems in production
+- For testing, generate test-only keys that don't hold real funds
+
 ## 📊 Example Output
 
 When running with multiple servers, you'll see:

bun.lock

@@ -0,0 +1,24 @@
+# Environment variables required for x402 payment gateway
+
+# Context7 API key for documentation MCP server
+# Get your API key from https://context7.com/dashboard
+CONTEXT7_API_KEY=
+
+# EVM wallet private keys for x402 payments
+# WARNING: Never commit actual private keys to version control!
+# For production, use a secure key management system
+X402_EVM_PRIVATE_KEY=
+X402_TEST_PRIVATE_KEY=
+
+# For testing only - use test network private keys
+# You can generate test keys using: npx ethereum-wallet-cli generate
+TEST_PRIVATE_KEY=
+
+# Test API key for testing SSE configurations
+TEST_API_KEY=test-api-key-123
+
+# Optional: Network configuration
+# X402_NETWORK=base-sepolia  # or 'base' for mainnet
+
+# Optional: Additional x402 configuration
+# X402_MAX_VALUE_MICRO_USDC=100000  # Max 0.10 USDC per request

env.example

@@ -0,0 +1,59 @@
+# Production example: Context7 MCP server with x402 payment middleware
+# 
+# Context7 provides up-to-date documentation for various libraries and frameworks.
+# By wrapping it with x402, you can monetize documentation lookups.
+#
+# Prerequisites:
+# 1. Get a Context7 API key from https://context7.com/dashboard
+# 2. Set up an EVM wallet with USDC on Base/Base-Sepolia
+# 3. Set environment variables:
+#    - CONTEXT7_API_KEY: Your Context7 API key
+#    - X402_CONTEXT7_PRIVATE_KEY: Your EVM wallet private key
+
+mcpServers:
+  # Context7 documentation service with x402 payments
+  context7-docs:
+    transport:
+      type: stdio
+      command: npx
+      args: 
+        - "-y"
+        - "@upstash/context7-mcp"
+        - "--api-key"
+        - "${CONTEXT7_API_KEY}"
+    
+    # x402 payment configuration
+    x402Middleware:
+      enabled: true
+      wallet:
+        type: evm
+        network: base  # Use base-sepolia for testing
+        privateKeyEnv: X402_CONTEXT7_PRIVATE_KEY
+      maxValueMicroUSDC: "50000"  # $0.05 per documentation lookup
+    
+    # Optional namespace to avoid tool name conflicts
+    namespace: "docs"
+    
+    # Enable this server
+    enabled: true
+    
+    # Connection settings
+    timeout: 60000  # 60 seconds - documentation lookups can take time
+    retryAttempts: 3
+    retryDelay: 2000
+
+# Example usage from your AI coding assistant:
+#
+# User: "use docs.resolve-library-id to find the react library"
+# Assistant calls: docs.resolve-library-id with { libraryName: "react" }
+# Result: Returns Context7 library ID like "/facebook/react"
+#
+# User: "use docs.get-library-docs to get react hooks documentation"  
+# Assistant calls: docs.get-library-docs with { 
+#   context7CompatibleLibraryID: "/facebook/react",
+#   topic: "hooks",
+#   tokens: 15000
+# }
+# Result: Returns comprehensive React hooks documentation
+#
+# Each successful call triggers a micro-payment via x402!

examples/context7-x402-production.yaml

@@ -21,6 +21,8 @@ servers:
       apiKey: "YOUR_CONTEXT7_API_KEY"
     namespace: "docs"
     enabled: true
+    # Enable per-server x402 payments (HTTP 402 handling with wallet)
+    x402Middleware: true
 
   # Local filesystem access
   - name: "filesystem"
@@ -41,6 +43,14 @@ servers:
         X-Company-Client: "mcp-aggregator"
     namespace: "db"
     enabled: false
+    # Advanced configuration example
+    x402Middleware:
+      enabled: true
+      wallet:
+        type: "evm"
+        network: "base" # or base-sepolia, solana-devnet, etc.
+        privateKeyEnv: "X402_EVM_PRIVATE_KEY"
+      maxValueMicroUSDC: "100000"
 
 settings:
   enableToolConflictResolution: true

examples/mixed-transports.yaml

@@ -0,0 +1,53 @@
+# Example configuration for x402 payment-enabled MCP servers
+
+mcpServers:
+  # Example 1: Simple x402 enablement
+  # Uses default settings: EVM wallet, base-sepolia network, 0.10 USDC limit
+  paid-weather-api:
+    transport:
+      type: http
+      url: https://api.weather-provider.com/mcp
+    x402Middleware: true
+    # Requires X402_EVM_PRIVATE_KEY environment variable
+    
+  # Example 2: Detailed x402 configuration
+  paid-llm-api:
+    transport:
+      type: http
+      url: https://api.llm-provider.com/v1/mcp
+      headers:
+        X-API-Version: "2024-01"
+    x402Middleware:
+      enabled: true
+      wallet:
+        type: evm                    # Wallet type (currently only 'evm' supported)
+        network: base               # Network: base, base-sepolia
+        privateKeyEnv: LLM_WALLET_KEY  # Custom env var for private key
+      maxValueMicroUSDC: "500000"   # Max 0.50 USDC per request
+    
+  # Example 3: SSE endpoint with x402
+  paid-realtime-data:
+    transport:
+      type: sse
+      sseUrl: https://stream.data-provider.com/events
+    x402Middleware:
+      enabled: true
+      wallet:
+        type: evm
+        network: base-sepolia
+        privateKeyEnv: X402_EVM_PRIVATE_KEY
+      maxValueMicroUSDC: "100000"   # Max 0.10 USDC per request
+    
+  # Example 4: Mixed setup - some servers with x402, some without
+  free-server:
+    transport:
+      type: stdio
+      command: node
+      args: ["./free-mcp-server.js"]
+    # No x402Middleware - this server is free to use
+    
+  premium-server:
+    transport:
+      type: http
+      url: https://premium.service.com/mcp
+    x402Middleware: true  # This server requires payment