Merge pull request #7 from elizaOS/feat/sse-default-mode

feat: Make SSE mode the default transport

Author: wtfsayo

CLAUDE.md

@@ -16,9 +16,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## COMMON COMMANDS
 
 ```bash
-# Development
-bun run start              # Start the gateway server
-bun run dev                # Start in development mode
+# Development - SSE Mode (default, exposes HTTP/SSE endpoints)
+bun run start --config=examples/config.yaml              # Start gateway in SSE mode on port 8000
+bun run start --config=examples/config.yaml --port=3000  # SSE mode on custom port
+bun run dev --config=examples/config.yaml                # Development SSE mode
+
+# Development - STDIO Mode (for Claude Desktop integration)
+bun run start:stdio --config=examples/config.yaml        # Start gateway in STDIO mode
+bun run dev:stdio --config=examples/config.yaml          # Development STDIO mode
+
+# Direct invocation with mode flags
+bun run src/index.ts --config=config.yaml --mode=sse --port=8000   # SSE mode (explicit)
+bun run src/index.ts --config=config.yaml --mode=stdio             # STDIO mode (explicit)
 
 # Testing
 bun run test               # Run comprehensive E2E tests
@@ -30,14 +39,14 @@ bun run test:quick         # Run fast, essential tests only (recommended during
 # Type Checking
 bun run type-check         # Run TypeScript type checking (no build output)
 
-# Testing with specific configs
-npx @modelcontextprotocol/inspector node build/index.js --config=examples/config.yaml
-
 # Testing with paid config
-bun run start --config=examples/paid-config.yaml
+bun run start --config=examples/paid-config.yaml --port=8000
 ```
 
-**IMPORTANT:** There is NO build, lint, or compilation step. The project runs directly from TypeScript source files using Bun. Only use `type-check` to validate types.
+**IMPORTANT:** 
+- There is NO build, lint, or compilation step. The project runs directly from TypeScript source files using Bun. Only use `type-check` to validate types.
+- **Default mode is SSE** (HTTP/SSE server), which exposes the gateway over HTTP with x402 payment support
+- **STDIO mode** is for local integrations (Claude Desktop, Cursor, etc.)
 
 ---
 
@@ -302,14 +311,29 @@ servers:
 ## IMPORTANT DEVELOPMENT NOTES
 
 ### Entry Point
-- `src/index.ts` is the CLI entry point
-- Accepts `--config=<path>` flag for configuration file
-- Falls back to environment variables if no config file provided
-- Creates STDIO transport and connects gateway server
-
-### Transport Priority
-- STDIO is the default and most common transport (local MCP servers)
-- HTTP/SSE/WebSocket are for remote servers (less common)
+- `src/index.ts` is the CLI entry point with dual-mode support
+- **SSE mode** (default): Runs HTTP/SSE wrapper for network access with x402 payment support
+- **STDIO mode**: Direct stdin/stdout for local clients (Claude Desktop, Cursor, etc.)
+- Accepts flags:
+  - `--config=<path>` - Configuration file path (required for SSE mode)
+  - `--mode=<sse|stdio>` - Transport mode (default: sse)
+  - `--port=<number>` - Port for SSE mode (default: 8000)
+- Falls back to environment variables if no config file provided (STDIO mode only)
+
+### Transport Modes
+- **SSE** (default): HTTP/SSE server mode - exposes gateway over HTTP with x402 payment support
+  - Used for: Network access, agent integrations, payment-gated APIs
+  - Endpoints: `GET /sse` (Server-Sent Events), `POST /message`
+- **STDIO**: Standard input/output mode - direct communication via stdin/stdout
+  - Used for: Claude Desktop, Cursor, local MCP clients, testing
+  - Required for all test suites
+
+### Downstream Server Transports
+Gateway can connect to downstream servers using:
+- **STDIO** - Most common (local MCP servers)
+- **HTTP/HTTPS** - Remote MCP servers
+- **SSE** - Streaming connections
+- **WebSocket** - Bidirectional real-time
 - Legacy format auto-converts to STDIO transport
 
 ### Logging System

example-agents/run-gateway-sse.sh

@@ -19,6 +19,8 @@ echo "━━━━━━━━━━━━━━━━━━━━━━━━
 
 cd "$(dirname "$0")/.."
 
-bun run src/transports/http-wrapper.ts \
+# SSE is now the default mode, so we can use the main entry point
+bun run src/index.ts \
     --config=$CONFIG_PATH \
+    --mode=sse \
     --port=$PORT

package.json

@@ -5,8 +5,11 @@
   "type": "module",
   "main": "build/index.js",
   "scripts": {
-    "start": "bun run src/index.ts",
-    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir build --target node --format esm --sourcemap=external",
+    "start": "bun run src/index.ts --config=examples/coingecko-config.yaml --mode=sse --port=8000",
+    "start:stdio": "bun run src/index.ts --config=examples/coingecko-config.yaml --mode=stdio",
+    "dev": "bun run src/index.ts --mode=sse",
+    "dev:stdio": "bun run src/index.ts --mode=stdio",
     "type-check": "tsc --noEmit",
     "test": "bun run tests/e2e-test.ts",
     "test:quick": "bun run tests/e2e-simple.ts",

src/index.ts

@@ -3,22 +3,49 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { GatewayServer } from './core/gateway.js';
 import { configManager } from './config/manager.js';
+import { HTTPGatewayWrapper } from './transports/http-wrapper.js';
+
+type TransportMode = 'stdio' | 'sse';
 
 /**
  * Main entry point for the MCP Gateway Server
  */
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
 
+  // Parse command line arguments
+  const configFile = args.find(arg => arg.startsWith('--config='))?.replace('--config=', '');
+  const modeArg = args.find(arg => arg.startsWith('--mode='))?.replace('--mode=', '') as TransportMode | undefined;
+  const portArg = args.find(arg => arg.startsWith('--port='))?.replace('--port=', '');
+  
+  // Default to SSE mode
+  const mode: TransportMode = modeArg || 'sse';
+  const port = portArg ? parseInt(portArg, 10) : 8000;
+  
   // Setup logging based on config (will be overridden by config later)
   const logLevel = process.env.MCP_LOG_LEVEL || 'info';
   const logger = createLogger(logLevel);
 
   try {
+    // SSE mode - start HTTP/SSE wrapper
+    if (mode === 'sse') {
+      if (!configFile) {
+        logger.error('SSE mode requires --config flag');
+        logger.info('Usage: bun run src/index.ts --config=path/to/config.yaml --mode=sse --port=8000');
+        process.exit(1);
+      }
+
+      logger.info(`Starting MCP Gateway in SSE mode on port ${port}`);
+      const wrapper = new HTTPGatewayWrapper(configFile, port, logger);
+      wrapper.start();
+      return;
+    }
+
+    // STDIO mode - run gateway directly
+    logger.info('Starting MCP Gateway in STDIO mode');
+
     // Load configuration
     let config;
-    const configFile = args.find(arg => arg.startsWith('--config='))?.replace('--config=', '');
-    
     if (configFile) {
       logger.info(`Loading configuration from file: ${configFile}`);
       config = configManager.loadFromFile(configFile);
@@ -129,8 +156,15 @@ USAGE:
 
 OPTIONS:
   --config=<path>    Path to configuration file (JSON or YAML)
+  --mode=<mode>      Transport mode: sse (default) or stdio
+  --port=<port>      Port for SSE mode (default: 8000)
   --help            Show this help message
 
+TRANSPORT MODES:
+  sse               HTTP/SSE server mode - exposes gateway over HTTP with x402 payment support
+                    Endpoints: GET /sse (Server-Sent Events), POST /message
+  stdio             Standard I/O mode - communicates via stdin/stdout (used by Claude Desktop)
+
 ENVIRONMENT VARIABLES:
   MCP_GATEWAY_NAME                       Name of the gateway (default: "MCP Gateway")
   MCP_GATEWAY_VERSION                    Version of the gateway (default: "1.0.0")
@@ -144,11 +178,17 @@ ENVIRONMENT VARIABLES:
   MCP_HEALTH_CHECK_INTERVAL             Health check interval in ms (default: 60000)
 
 EXAMPLES:
-  # Run with configuration file
-  mcp-gateway --config=config.yaml
+  # Run in SSE mode (default) - HTTP server with x402 payments
+  mcp-gateway --config=config.yaml --port=8000
+  
+  # Explicitly specify SSE mode
+  mcp-gateway --config=config.yaml --mode=sse --port=8000
+
+  # Run in STDIO mode (for Claude Desktop integration)
+  mcp-gateway --config=config.yaml --mode=stdio
 
-  # Run with environment variables
-  MCP_SERVERS="weather:node:weather.js;filesystem:python:fs_server.py" mcp-gateway
+  # Run with environment variables (STDIO mode)
+  MCP_SERVERS="weather:node:weather.js;filesystem:python:fs_server.py" mcp-gateway --mode=stdio
 
 For more information, visit: https://github.com/studio/mcp-gateway
 `);

src/transports/http-wrapper.ts

@@ -45,11 +45,17 @@ class HTTPGatewayWrapper {
 
     // Gateway subprocess command - use wrapper config (no payment checking in subprocess)
     // The HTTP layer handles all payment verification
-    const gatewayPath = new URL('../index.ts', import.meta.url).pathname;
+    // IMPORTANT: Subprocess must run in STDIO mode, not SSE mode
+    
+    // Just re-run the same script we're currently running, but in STDIO mode
+    // process.argv[1] is the path to the currently executing script (works for both src and build)
+    // Use 'bun' directly (not 'bun run') to execute the script without package.json interference
+    const currentScript = process.argv[1]!;
     const wrapperConfigPath = configPath.replace('.yaml', '-wrapper.yaml').replace('.json', '-wrapper.json');
-    this.gatewayCommand = ['bun', 'run', gatewayPath, `--config=${wrapperConfigPath}`];
+    this.gatewayCommand = ['bun', currentScript, '--mode=stdio', `--config=${wrapperConfigPath}`];
 
     logger.info(`Gateway subprocess will use config: ${wrapperConfigPath}`);
+    logger.info(`Gateway subprocess command: ${this.gatewayCommand.join(' ')}`);
   }
 
   start(): void {

tests/e2e-passthrough.ts

@@ -246,6 +246,7 @@ class PassthroughE2ETestRunner {
       const gatewayProcess: ChildProcess = spawn('bun', [
         'run',
         'src/index.ts',
+        '--mode=stdio',
         `--config=${configPath}`
       ], {
         cwd: process.cwd(),

tests/e2e-payment.ts

@@ -282,7 +282,7 @@ class PaymentE2ETestRunner {
 
   private async runGatewayWithTimeout(configPath: string, timeoutMs: number = 8000): Promise<string> {
     return new Promise((resolve, reject) => {
-      const args = ['run', 'src/index.ts', `--config=${configPath}`];
+      const args = ['run', 'src/index.ts', '--mode=stdio', `--config=${configPath}`];
 
       const gatewayProcess = spawn('bun', args, {
         stdio: ['pipe', 'pipe', 'pipe'],

tests/e2e-simple.ts

@@ -236,7 +236,7 @@ class SimpleE2ETestRunner {
 
   private async runGatewayWithTimeout(configPath?: string, timeoutMs: number = 5000): Promise<string> {
     return new Promise((resolve, reject) => {
-      const args = ['run', 'src/index.ts'];
+      const args = ['run', 'src/index.ts', '--mode=stdio'];
       if (configPath) {
         args.push(`--config=${configPath}`);
       }

tests/e2e-test.ts

@@ -301,7 +301,7 @@ class E2ETestRunner {
   }
 
   private async startGateway(configPath?: string): Promise<void> {
-    const args = ['run', 'src/index.ts'];
+    const args = ['run', 'src/index.ts', '--mode=stdio'];
     if (configPath) {
       args.push(`--config=${configPath}`);
     }

tests/test-runner.sh

@@ -90,7 +90,7 @@ test_config() {
     echo "Press Ctrl+C to stop..."
     echo ""
 
-    bun run src/index.ts --config="tests/configs/$config_file"
+    bun run src/index.ts --mode=stdio --config="tests/configs/$config_file"
 }
 
 # Function to run manual testing with inspector
@@ -110,7 +110,7 @@ run_manual_test() {
     echo "This will open the MCP Inspector for interactive testing..."
     echo ""
 
-    bun x @modelcontextprotocol/inspector bun run src/index.ts --config="tests/configs/$config_file"
+    bun x @modelcontextprotocol/inspector bun run src/index.ts --mode=stdio --config="tests/configs/$config_file"
 }
 
 # Function to show usage