cprime-supergateway 3.4.3

package/src/gateways/stdioToWs.ts

@@ -0,0 +1,151 @@
+import express from 'express'
+import cors, { type CorsOptions } from 'cors'
+import { createServer } from 'http'
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js'
+import { Logger } from '../types.js'
+import { getVersion } from '../lib/getVersion.js'
+import { WebSocketServerTransport } from '../server/websocket.js'
+import { onSignals } from '../lib/onSignals.js'
+import { serializeCorsOrigin } from '../lib/serializeCorsOrigin.js'
+
+export interface StdioToWsArgs {
+  stdioCmd: string
+  port: number
+  messagePath: string
+  logger: Logger
+  corsOrigin: CorsOptions['origin']
+  healthEndpoints: string[]
+}
+
+export async function stdioToWs(args: StdioToWsArgs) {
+  const { stdioCmd, port, messagePath, logger, healthEndpoints, corsOrigin } =
+    args
+  logger.info(`  - port: ${port}`)
+  logger.info(`  - stdio: ${stdioCmd}`)
+  logger.info(`  - messagePath: ${messagePath}`)
+  logger.info(
+    `  - CORS: ${corsOrigin ? `enabled (${serializeCorsOrigin({ corsOrigin })})` : 'disabled'}`,
+  )
+  logger.info(
+    `  - Health endpoints: ${healthEndpoints.length ? healthEndpoints.join(', ') : '(none)'}`,
+  )
+
+  let wsTransport: WebSocketServerTransport | null = null
+  let child: ChildProcessWithoutNullStreams | null = null
+  let isReady = false
+
+  const cleanup = () => {
+    if (wsTransport) {
+      wsTransport.close().catch((err) => {
+        logger.error(`Error stopping WebSocket server: ${err.message}`)
+      })
+    }
+    if (child) {
+      child.kill()
+    }
+  }
+
+  onSignals({
+    logger,
+    cleanup,
+  })
+
+  try {
+    child = spawn(stdioCmd, { shell: true })
+    child.on('exit', (code, signal) => {
+      logger.error(`Child exited: code=${code}, signal=${signal}`)
+      cleanup()
+      process.exit(code ?? 1)
+    })
+
+    const server = new Server(
+      { name: 'supergateway', version: getVersion() },
+      { capabilities: {} },
+    )
+
+    // Handle child process output
+    let buffer = ''
+    child.stdout.on('data', (chunk: Buffer) => {
+      buffer += chunk.toString('utf8')
+      const lines = buffer.split(/\r?\n/)
+      buffer = lines.pop() ?? ''
+      lines.forEach((line) => {
+        if (!line.trim()) return
+        try {
+          const jsonMsg = JSON.parse(line)
+          logger.info(`Child → WebSocket: ${JSON.stringify(jsonMsg)}`)
+          // Broadcast to all connected clients
+          wsTransport?.send(jsonMsg, jsonMsg.id).catch((err) => {
+            logger.error('Failed to broadcast message:', err)
+          })
+        } catch {
+          logger.error(`Child non-JSON: ${line}`)
+        }
+      })
+    })
+
+    child.stderr.on('data', (chunk: Buffer) => {
+      logger.info(`Child stderr: ${chunk.toString('utf8')}`)
+    })
+
+    const app = express()
+
+    if (corsOrigin) {
+      app.use(cors({ origin: corsOrigin }))
+    }
+
+    for (const ep of healthEndpoints) {
+      app.get(ep, (_req, res) => {
+        if (child?.killed) {
+          res.status(500).send('Child process has been killed')
+        }
+
+        if (!isReady) {
+          res.status(500).send('Server is not ready')
+        }
+
+        res.send('ok')
+      })
+    }
+
+    const httpServer = createServer(app)
+
+    wsTransport = new WebSocketServerTransport({
+      path: messagePath,
+      server: httpServer,
+    })
+
+    await server.connect(wsTransport)
+
+    wsTransport.onmessage = (msg: JSONRPCMessage) => {
+      const line = JSON.stringify(msg)
+      logger.info(`WebSocket → Child: ${line}`)
+      child!.stdin.write(line + '\n')
+    }
+
+    wsTransport.onconnection = (clientId: string) => {
+      logger.info(`New WebSocket connection: ${clientId}`)
+    }
+
+    wsTransport.ondisconnection = (clientId: string) => {
+      logger.info(`WebSocket connection closed: ${clientId}`)
+    }
+
+    wsTransport.onerror = (err: Error) => {
+      logger.error(`WebSocket error: ${err.message}`)
+    }
+
+    isReady = true
+
+    httpServer.listen(port, () => {
+      logger.info(`Listening on port ${port}`)
+      logger.info(`WebSocket endpoint: ws://localhost:${port}${messagePath}`)
+    })
+  } catch (err: any) {
+    logger.error(`Failed to start: ${err.message}`)
+    cleanup()
+    process.exit(1)
+  }
+}

package/src/gateways/streamableHttpToStdio.ts

@@ -0,0 +1,196 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type {
+  JSONRPCMessage,
+  JSONRPCRequest,
+  ClientCapabilities,
+  Implementation,
+} from '@modelcontextprotocol/sdk/types.js'
+import { InitializeRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import { getVersion } from '../lib/getVersion.js'
+import { Logger } from '../types.js'
+import { onSignals } from '../lib/onSignals.js'
+
+export interface StreamableHttpToStdioArgs {
+  streamableHttpUrl: string
+  logger: Logger
+  headers: Record<string, string>
+}
+
+let mcpClient: Client | undefined
+
+const newInitializeMcpClient = ({ message }: { message: JSONRPCRequest }) => {
+  const clientInfo = message.params?.clientInfo as Implementation | undefined
+  const clientCapabilities = message.params?.capabilities as
+    | ClientCapabilities
+    | undefined
+
+  return new Client(
+    {
+      name: clientInfo?.name ?? 'supergateway',
+      version: clientInfo?.version ?? getVersion(),
+    },
+    {
+      capabilities: clientCapabilities ?? {},
+    },
+  )
+}
+
+const newFallbackMcpClient = async ({
+  mcpTransport,
+}: {
+  mcpTransport: StreamableHTTPClientTransport
+}) => {
+  const fallbackMcpClient = new Client(
+    {
+      name: 'supergateway',
+      version: getVersion(),
+    },
+    {
+      capabilities: {},
+    },
+  )
+
+  await fallbackMcpClient.connect(mcpTransport)
+  return fallbackMcpClient
+}
+
+export async function streamableHttpToStdio(args: StreamableHttpToStdioArgs) {
+  const { streamableHttpUrl, logger, headers } = args
+
+  logger.info(`  - streamableHttp: ${streamableHttpUrl}`)
+  logger.info(
+    `  - Headers: ${Object.keys(headers).length ? JSON.stringify(headers) : '(none)'}`,
+  )
+  logger.info('Connecting to Streamable HTTP...')
+
+  onSignals({ logger })
+
+  const mcpTransport = new StreamableHTTPClientTransport(
+    new URL(streamableHttpUrl),
+    {
+      requestInit: {
+        headers,
+      },
+    },
+  )
+
+  mcpTransport.onerror = (err) => {
+    logger.error('Streamable HTTP error:', err)
+  }
+
+  mcpTransport.onclose = () => {
+    logger.error('Streamable HTTP connection closed')
+    process.exit(1)
+  }
+
+  const stdioServer = new Server(
+    {
+      name: 'supergateway',
+      version: getVersion(),
+    },
+    {
+      capabilities: {},
+    },
+  )
+
+  const stdioTransport = new StdioServerTransport()
+  await stdioServer.connect(stdioTransport)
+
+  const wrapResponse = (req: JSONRPCRequest, payload: object) => ({
+    jsonrpc: req.jsonrpc || '2.0',
+    id: req.id,
+    ...payload,
+  })
+
+  stdioServer.transport!.onmessage = async (message: JSONRPCMessage) => {
+    const isRequest = 'method' in message && 'id' in message
+    if (isRequest) {
+      logger.info('Stdio → Streamable HTTP:', message)
+      const req = message as JSONRPCRequest
+      let result
+
+      try {
+        if (!mcpClient) {
+          if (message.method === 'initialize') {
+            mcpClient = newInitializeMcpClient({
+              message,
+            })
+
+            const originalRequest = mcpClient.request
+
+            mcpClient.request = async function (
+              possibleInitRequestMessage,
+              ...restArgs
+            ) {
+              if (
+                InitializeRequestSchema.safeParse(possibleInitRequestMessage)
+                  .success &&
+                message.params?.protocolVersion
+              ) {
+                // respect the protocol version from the stdio client's init request
+                possibleInitRequestMessage.params!.protocolVersion =
+                  message.params.protocolVersion
+              }
+              result = await originalRequest.apply(this, [
+                possibleInitRequestMessage,
+                ...restArgs,
+              ])
+              return result
+            }
+
+            await mcpClient.connect(mcpTransport)
+            mcpClient.request = originalRequest
+          } else {
+            logger.info(
+              'Streamable HTTP client not initialized, creating fallback client',
+            )
+            mcpClient = await newFallbackMcpClient({ mcpTransport })
+          }
+
+          logger.info('Streamable HTTP connected')
+        } else {
+          result = await mcpClient.request(req, z.any())
+        }
+      } catch (err) {
+        logger.error('Request error:', err)
+        const errorCode =
+          err && typeof err === 'object' && 'code' in err
+            ? (err as any).code
+            : -32000
+        let errorMsg =
+          err && typeof err === 'object' && 'message' in err
+            ? (err as any).message
+            : 'Internal error'
+        const prefix = `MCP error ${errorCode}:`
+        if (errorMsg.startsWith(prefix)) {
+          errorMsg = errorMsg.slice(prefix.length).trim()
+        }
+        const errorResp = wrapResponse(req, {
+          error: {
+            code: errorCode,
+            message: errorMsg,
+          },
+        })
+        process.stdout.write(JSON.stringify(errorResp) + '\n')
+        return
+      }
+      const response = wrapResponse(
+        req,
+        result.hasOwnProperty('error')
+          ? { error: { ...result.error } }
+          : { result: { ...result } },
+      )
+      logger.info('Response:', response)
+      process.stdout.write(JSON.stringify(response) + '\n')
+    } else {
+      logger.info('Streamable HTTP → Stdio:', message)
+      process.stdout.write(JSON.stringify(message) + '\n')
+    }
+  }
+
+  logger.info('Stdio server listening')
+}

package/src/index.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * index.ts
+ *
+ * Run MCP stdio servers over SSE, convert between stdio, SSE, WS.
+ *
+ * Usage:
+ *   # stdio→SSE
+ *   npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem /" \
+ *                       --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message
+ *
+ *   # SSE→stdio
+ *   npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+ *
+ *   # stdio→WS
+ *   npx -y supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem /" --outputTransport ws
+ *
+ *   # Streamable HTTP→stdio
+ *   npx -y supergateway --streamableHttp "https://mcp-server.example.com/mcp"
+ */
+
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+import { stdioToSse } from './gateways/stdioToSse.js'
+import { sseToStdio } from './gateways/sseToStdio.js'
+import { stdioToWs } from './gateways/stdioToWs.js'
+import { streamableHttpToStdio } from './gateways/streamableHttpToStdio.js'
+import { headers } from './lib/headers.js'
+import { corsOrigin } from './lib/corsOrigin.js'
+import { getLogger } from './lib/getLogger.js'
+import { stdioToStatelessStreamableHttp } from './gateways/stdioToStatelessStreamableHttp.js'
+import { stdioToStatefulStreamableHttp } from './gateways/stdioToStatefulStreamableHttp.js'
+
+async function main() {
+  const argv = yargs(hideBin(process.argv))
+    .option('stdio', {
+      type: 'string',
+      description: 'Command to run an MCP server over Stdio',
+    })
+    .option('sse', {
+      type: 'string',
+      description: 'SSE URL to connect to',
+    })
+    .option('streamableHttp', {
+      type: 'string',
+      description: 'Streamable HTTP URL to connect to',
+    })
+    .option('outputTransport', {
+      type: 'string',
+      choices: ['stdio', 'sse', 'ws', 'streamableHttp'],
+      default: () => {
+        const args = hideBin(process.argv)
+
+        if (args.includes('--stdio')) return 'sse'
+        if (args.includes('--sse')) return 'stdio'
+        if (args.includes('--streamableHttp')) return 'stdio'
+
+        return undefined
+      },
+      description:
+        'Transport for output. Default is "sse" when using --stdio and "stdio" when using --sse or --streamableHttp.',
+    })
+    .option('port', {
+      type: 'number',
+      default: 8000,
+      description: '(stdio→SSE, stdio→WS) Port for output MCP server',
+    })
+    .option('baseUrl', {
+      type: 'string',
+      default: '',
+      description: '(stdio→SSE) Base URL for output MCP server',
+    })
+    .option('ssePath', {
+      type: 'string',
+      default: '/sse',
+      description: '(stdio→SSE) Path for SSE subscriptions',
+    })
+    .option('messagePath', {
+      type: 'string',
+      default: '/message',
+      description: '(stdio→SSE, stdio→WS) Path for messages',
+    })
+    .option('streamableHttpPath', {
+      type: 'string',
+      default: '/mcp',
+      description: '(stdio→StreamableHttp) Path for StreamableHttp',
+    })
+    .option('logLevel', {
+      choices: ['debug', 'info', 'none'] as const,
+      default: 'info',
+      description: 'Logging level',
+    })
+    .option('cors', {
+      type: 'array',
+      description:
+        'Enable CORS. Use --cors with no values to allow all origins, or supply one or more allowed origins (e.g. --cors "http://example.com" or --cors "/example\\.com$/" for regex matching).',
+    })
+    .option('healthEndpoint', {
+      type: 'array',
+      default: [],
+      description:
+        'One or more endpoints returning "ok", e.g. --healthEndpoint /healthz --healthEndpoint /readyz',
+    })
+    .option('header', {
+      type: 'array',
+      default: [],
+      description:
+        'Headers to be added to the request headers, e.g. --header "x-user-id: 123"',
+    })
+    .option('oauth2Bearer', {
+      type: 'string',
+      description:
+        'Authorization header to be added, e.g. --oauth2Bearer "some-access-token" adds "Authorization: Bearer some-access-token"',
+    })
+    .option('stateful', {
+      type: 'boolean',
+      default: false,
+      description:
+        'Whether the server is stateful. Only supported for stdio→StreamableHttp.',
+    })
+    .option('sessionTimeout', {
+      type: 'number',
+      description:
+        'Session timeout in milliseconds. Only supported for stateful stdio→StreamableHttp. If not set, the session will only be deleted when client transport explicitly terminates the session.',
+    })
+    .option('protocolVersion', {
+      type: 'string',
+      description:
+        'MCP protocol version to use for auto-initialization. Defaults to "2024-11-05" if not specified.',
+      default: '2024-11-05',
+    })
+    .help()
+    .parseSync()
+
+  const hasStdio = Boolean(argv.stdio)
+  const hasSse = Boolean(argv.sse)
+  const hasStreamableHttp = Boolean(argv.streamableHttp)
+
+  const activeCount = [hasStdio, hasSse, hasStreamableHttp].filter(
+    Boolean,
+  ).length
+
+  const logger = getLogger({
+    logLevel: argv.logLevel,
+    outputTransport: argv.outputTransport as string,
+  })
+
+  if (activeCount === 0) {
+    logger.error(
+      'Error: You must specify one of --stdio, --sse, or --streamableHttp',
+    )
+    process.exit(1)
+  } else if (activeCount > 1) {
+    logger.error(
+      'Error: Specify only one of --stdio, --sse, or --streamableHttp, not multiple',
+    )
+    process.exit(1)
+  }
+
+  logger.info('Starting...')
+  logger.info(
+    'Supergateway is supported by Supermachine (hosted MCPs) - https://supermachine.ai',
+  )
+  logger.info(`  - outputTransport: ${argv.outputTransport}`)
+
+  try {
+    if (hasStdio) {
+      if (argv.outputTransport === 'sse') {
+        await stdioToSse({
+          stdioCmd: argv.stdio!,
+          port: argv.port,
+          baseUrl: argv.baseUrl,
+          ssePath: argv.ssePath,
+          messagePath: argv.messagePath,
+          logger,
+          corsOrigin: corsOrigin({ argv }),
+          healthEndpoints: argv.healthEndpoint as string[],
+          headers: headers({
+            argv,
+            logger,
+          }),
+        })
+      } else if (argv.outputTransport === 'ws') {
+        await stdioToWs({
+          stdioCmd: argv.stdio!,
+          port: argv.port,
+          messagePath: argv.messagePath,
+          logger,
+          corsOrigin: corsOrigin({ argv }),
+          healthEndpoints: argv.healthEndpoint as string[],
+        })
+      } else if (argv.outputTransport === 'streamableHttp') {
+        const stateful = argv.stateful
+        if (stateful) {
+          logger.info('Running stateful server')
+
+          let sessionTimeout: null | number
+          if (typeof argv.sessionTimeout === 'number') {
+            if (argv.sessionTimeout <= 0) {
+              logger.error(
+                `Error: \`sessionTimeout\` must be a positive number, received: ${argv.sessionTimeout}`,
+              )
+              process.exit(1)
+            }
+
+            sessionTimeout = argv.sessionTimeout
+          } else {
+            sessionTimeout = null
+          }
+
+          await stdioToStatefulStreamableHttp({
+            stdioCmd: argv.stdio!,
+            port: argv.port,
+            streamableHttpPath: argv.streamableHttpPath,
+            logger,
+            corsOrigin: corsOrigin({ argv }),
+            healthEndpoints: argv.healthEndpoint as string[],
+            headers: headers({
+              argv,
+              logger,
+            }),
+            sessionTimeout,
+          })
+        } else {
+          logger.info('Running stateless server')
+
+          await stdioToStatelessStreamableHttp({
+            stdioCmd: argv.stdio!,
+            port: argv.port,
+            streamableHttpPath: argv.streamableHttpPath,
+            logger,
+            corsOrigin: corsOrigin({ argv }),
+            healthEndpoints: argv.healthEndpoint as string[],
+            headers: headers({
+              argv,
+              logger,
+            }),
+            protocolVersion: argv.protocolVersion,
+          })
+        }
+      } else {
+        logger.error(`Error: stdio→${argv.outputTransport} not supported`)
+        process.exit(1)
+      }
+    } else if (hasSse) {
+      if (argv.outputTransport === 'stdio') {
+        await sseToStdio({
+          sseUrl: argv.sse!,
+          logger,
+          headers: headers({
+            argv,
+            logger,
+          }),
+        })
+      } else {
+        logger.error(`Error: sse→${argv.outputTransport} not supported`)
+        process.exit(1)
+      }
+    } else if (hasStreamableHttp) {
+      if (argv.outputTransport === 'stdio') {
+        await streamableHttpToStdio({
+          streamableHttpUrl: argv.streamableHttp!,
+          logger,
+          headers: headers({
+            argv,
+            logger,
+          }),
+        })
+      } else {
+        logger.error(
+          `Error: streamableHttp→${argv.outputTransport} not supported`,
+        )
+        process.exit(1)
+      }
+    } else {
+      logger.error('Error: Invalid input transport')
+      process.exit(1)
+    }
+  } catch (err) {
+    logger.error('Fatal error:', err)
+    process.exit(1)
+  }
+}
+
+main()
+// test commit

package/src/lib/corsOrigin.ts

@@ -0,0 +1,31 @@
+export const corsOrigin = ({
+  argv,
+}: {
+  argv: {
+    cors: (string | number)[] | undefined
+  }
+}) => {
+  if (!argv.cors) {
+    return false
+  }
+
+  if (argv.cors.length === 0) {
+    return '*'
+  }
+
+  const origins = argv.cors.map((item) => `${item}`)
+
+  if (origins.includes('*')) return '*'
+
+  return origins.map((origin) => {
+    if (/^\/.*\/$/.test(origin)) {
+      const pattern = origin.slice(1, -1)
+      try {
+        return new RegExp(pattern)
+      } catch (error) {
+        return origin
+      }
+    }
+    return origin
+  })
+}