@platf/bridge 0.0.2

package/src/gateways/statefulBridge.ts

@@ -0,0 +1,271 @@
+import express from 'express'
+import cors, { type CorsOptions } from 'cors'
+import { spawn } from 'child_process'
+import { randomUUID } from 'node:crypto'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { type JSONRPCMessage, isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'
+import type { AuthConfig, Logger } from '../types.js'
+import { onSignals } from '../lib/onSignals.js'
+import { serializeCorsOrigin } from '../lib/cors.js'
+import { SessionAccessCounter } from '../lib/sessionAccessCounter.js'
+import { createAuthMiddleware } from '../lib/authMiddleware.js'
+import { createDiscoveryRouter } from '../lib/discoveryRoutes.js'
+
+const VERSION = '1.0.0'
+
+export interface StatefulBridgeArgs {
+  stdioCmd: string
+  port: number
+  path: string
+  logger: Logger
+  corsOrigin: CorsOptions['origin']
+  healthEndpoints: string[]
+  headers: Record<string, string>
+  sessionTimeout: number | null
+  auth: AuthConfig | null
+}
+
+const setResponseHeaders = (res: express.Response, headers: Record<string, string>) =>
+  Object.entries(headers).forEach(([key, value]) => res.setHeader(key, value))
+
+/**
+ * Stateful stdio-to-Streamable HTTP bridge.
+ *
+ * Maintains session state via `Mcp-Session-Id` header.  Each session
+ * spawns one child process; subsequent requests for the same session
+ * reuse the existing transport and process.  Sessions are cleaned up
+ * after an optional inactivity timeout.
+ */
+export async function startStatefulBridge(args: StatefulBridgeArgs) {
+  const {
+    stdioCmd,
+    port,
+    path,
+    logger,
+    corsOrigin,
+    healthEndpoints,
+    headers,
+    sessionTimeout,
+    auth,
+  } = args
+
+  logger.info(`[stateful] Starting platf-bridge`)
+  logger.info(`  - Headers: ${Object.keys(headers).length ? JSON.stringify(headers) : '(none)'}`)
+  logger.info(`  - port: ${port}`)
+  logger.info(`  - stdio: ${stdioCmd}`)
+  logger.info(`  - path: ${path}`)
+  logger.info(
+    `  - CORS: ${corsOrigin ? `enabled (${serializeCorsOrigin(corsOrigin)})` : 'disabled'}`,
+  )
+  logger.info(
+    `  - Health endpoints: ${healthEndpoints.length ? healthEndpoints.join(', ') : '(none)'}`,
+  )
+  logger.info(`  - Session timeout: ${sessionTimeout ? `${sessionTimeout}ms` : 'disabled'}`)
+
+  onSignals({ logger })
+
+  const app = express()
+  app.use(express.json())
+
+  if (corsOrigin) {
+    app.use(cors({ origin: corsOrigin, exposedHeaders: ['Mcp-Session-Id'] }))
+  }
+
+  for (const ep of healthEndpoints) {
+    app.get(ep, (_req, res) => {
+      setResponseHeaders(res, headers)
+      res.send('ok')
+    })
+  }
+
+  // --- OAuth discovery & auth middleware (when auth is enabled) ---
+  if (auth) {
+    app.use(createDiscoveryRouter(auth, logger))
+    app.use(path, createAuthMiddleware(auth, logger))
+    logger.info(`  - Auth: enabled (issuer=${auth.issuer})`)
+  }
+
+  // Session state
+  const transports: Record<string, StreamableHTTPServerTransport> = {}
+
+  const sessionCounter = sessionTimeout
+    ? new SessionAccessCounter(
+        sessionTimeout,
+        (sessionId) => {
+          logger.info(`Session ${sessionId} timed out, cleaning up`)
+          const transport = transports[sessionId]
+          if (transport) transport.close()
+          delete transports[sessionId]
+        },
+        logger,
+      )
+    : null
+
+  // --- POST handler ---
+  app.post(path, async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined
+    let transport: StreamableHTTPServerTransport
+
+    if (sessionId && transports[sessionId]) {
+      // Reuse existing session
+      transport = transports[sessionId]
+      sessionCounter?.inc(sessionId, 'POST request for existing session')
+    } else if (!sessionId && isInitializeRequest(req.body)) {
+      // New session — spawn child process
+      const server = new Server(
+        { name: 'platf-bridge', version: VERSION },
+        { capabilities: {} },
+      )
+
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (newSessionId) => {
+          transports[newSessionId] = transport
+          sessionCounter?.inc(newSessionId, 'session initialization')
+        },
+      })
+
+      await server.connect(transport)
+      const child = spawn(stdioCmd, { shell: true })
+
+      const pendingRequestIds = new Set<string | number>()
+      let stderrOutput = ''
+
+      child.on('exit', (code, signal) => {
+        logger.error(`Child exited: code=${code}, signal=${signal}`)
+
+        // Send JSON-RPC error responses for all pending requests
+        for (const id of pendingRequestIds) {
+          const detail = stderrOutput.trim().slice(0, 1000)
+          const message = detail
+            ? `Child process exited (code=${code}): ${detail}`
+            : `Child process exited unexpectedly (code=${code}, signal=${signal})`
+          try {
+            transport.send({
+              jsonrpc: '2.0',
+              error: { code: -32603, message },
+              id,
+            } as JSONRPCMessage)
+          } catch (e) {
+            logger.error(`Failed to send error response for request ${id}`, e)
+          }
+        }
+        pendingRequestIds.clear()
+
+        transport.close()
+      })
+
+      let buffer = ''
+      child.stdout.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString('utf8')
+        const lines = buffer.split(/\r?\n/)
+        buffer = lines.pop() ?? ''
+
+        for (const line of lines) {
+          if (!line.trim()) continue
+          try {
+            const jsonMsg = JSON.parse(line)
+            if ('id' in jsonMsg && jsonMsg.id !== undefined) {
+              pendingRequestIds.delete(jsonMsg.id)
+            }
+            logger.info('Child → HTTP:', line)
+            try {
+              transport.send(jsonMsg)
+            } catch (e) {
+              logger.error('Failed to send to HTTP transport', e)
+            }
+          } catch {
+            logger.error(`Child non-JSON: ${line}`)
+          }
+        }
+      })
+
+      child.stderr.on('data', (chunk: Buffer) => {
+        const text = chunk.toString('utf8')
+        stderrOutput += text
+        logger.error(`Child stderr: ${text}`)
+      })
+
+      transport.onmessage = (msg: JSONRPCMessage) => {
+        logger.info(`HTTP → Child: ${JSON.stringify(msg)}`)
+        if ('id' in msg && msg.id !== undefined) {
+          pendingRequestIds.add(msg.id as string | number)
+        }
+        child.stdin.write(JSON.stringify(msg) + '\n')
+      }
+
+      transport.onclose = () => {
+        logger.info(`HTTP connection closed (session ${sessionId})`)
+        if (transport.sessionId) {
+          sessionCounter?.clear(transport.sessionId, false, 'transport closed')
+          delete transports[transport.sessionId]
+        }
+        child.kill()
+      }
+
+      transport.onerror = (err) => {
+        logger.error(`HTTP transport error (session ${sessionId}):`, err)
+        if (transport.sessionId) {
+          sessionCounter?.clear(transport.sessionId, false, 'transport error')
+          delete transports[transport.sessionId]
+        }
+        child.kill()
+      }
+    } else {
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
+        id: null,
+      })
+      return
+    }
+
+    // Track response lifecycle for session cleanup
+    let responseEnded = false
+    const handleResponseEnd = (event: string) => {
+      if (!responseEnded && transport.sessionId) {
+        responseEnded = true
+        logger.info(`Response ${event}`, transport.sessionId)
+        sessionCounter?.dec(transport.sessionId, `POST response ${event}`)
+      }
+    }
+    res.on('finish', () => handleResponseEnd('finished'))
+    res.on('close', () => handleResponseEnd('closed'))
+
+    await transport.handleRequest(req, res, req.body)
+  })
+
+  // --- GET / DELETE handler (session-bound) ---
+  const handleSessionRequest = async (req: express.Request, res: express.Response) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined
+    if (!sessionId || !transports[sessionId]) {
+      res.status(400).send('Invalid or missing session ID')
+      return
+    }
+
+    sessionCounter?.inc(sessionId, `${req.method} request for existing session`)
+
+    let responseEnded = false
+    const handleResponseEnd = (event: string) => {
+      if (!responseEnded) {
+        responseEnded = true
+        logger.info(`Response ${event}`, sessionId)
+        sessionCounter?.dec(sessionId, `${req.method} response ${event}`)
+      }
+    }
+    res.on('finish', () => handleResponseEnd('finished'))
+    res.on('close', () => handleResponseEnd('closed'))
+
+    const transport = transports[sessionId]
+    await transport.handleRequest(req, res)
+  }
+
+  app.get(path, handleSessionRequest)
+  app.delete(path, handleSessionRequest)
+
+  app.listen(port, () => {
+    logger.info(`Listening on port ${port}`)
+    logger.info(`Streamable HTTP endpoint: http://localhost:${port}${path}`)
+  })
+}

package/src/gateways/statelessBridge.ts

@@ -0,0 +1,310 @@
+import express from 'express'
+import cors, { type CorsOptions } from 'cors'
+import { spawn } from 'child_process'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import {
+  type JSONRPCMessage,
+  isInitializeRequest,
+} from '@modelcontextprotocol/sdk/types.js'
+import type { AuthConfig, Logger } from '../types.js'
+import { onSignals } from '../lib/onSignals.js'
+import { serializeCorsOrigin } from '../lib/cors.js'
+import { createAuthMiddleware } from '../lib/authMiddleware.js'
+import { createDiscoveryRouter } from '../lib/discoveryRoutes.js'
+
+const VERSION = '1.0.0'
+
+export interface StatelessBridgeArgs {
+  stdioCmd: string
+  port: number
+  path: string
+  logger: Logger
+  corsOrigin: CorsOptions['origin']
+  healthEndpoints: string[]
+  headers: Record<string, string>
+  protocolVersion: string
+  auth: AuthConfig | null
+}
+
+const setResponseHeaders = (res: express.Response, headers: Record<string, string>) =>
+  Object.entries(headers).forEach(([key, value]) => res.setHeader(key, value))
+
+/** Create a synthetic MCP initialize request */
+const createInitializeRequest = (
+  id: string | number,
+  protocolVersion: string,
+): JSONRPCMessage => ({
+  jsonrpc: '2.0',
+  id,
+  method: 'initialize',
+  params: {
+    protocolVersion,
+    capabilities: {
+      roots: { listChanged: true },
+      sampling: {},
+    },
+    clientInfo: {
+      name: 'platf-bridge',
+      version: VERSION,
+    },
+  },
+})
+
+const createInitializedNotification = (): JSONRPCMessage => ({
+  jsonrpc: '2.0',
+  method: 'notifications/initialized',
+})
+
+/**
+ * Stateless stdio-to-Streamable HTTP bridge.
+ *
+ * For every incoming POST request, spawns a fresh child process,
+ * auto-initializes it if the request is not an initialize request,
+ * and proxies JSON-RPC messages between the HTTP transport and the
+ * child's stdin/stdout.
+ */
+export async function startStatelessBridge(args: StatelessBridgeArgs) {
+  const {
+    stdioCmd,
+    port,
+    path,
+    logger,
+    corsOrigin,
+    healthEndpoints,
+    headers,
+    protocolVersion,
+    auth,
+  } = args
+
+  logger.info(`[stateless] Starting platf-bridge`)
+  logger.info(`  - Headers: ${Object.keys(headers).length ? JSON.stringify(headers) : '(none)'}`)
+  logger.info(`  - port: ${port}`)
+  logger.info(`  - stdio: ${stdioCmd}`)
+  logger.info(`  - path: ${path}`)
+  logger.info(`  - protocolVersion: ${protocolVersion}`)
+  logger.info(
+    `  - CORS: ${corsOrigin ? `enabled (${serializeCorsOrigin(corsOrigin)})` : 'disabled'}`,
+  )
+  logger.info(
+    `  - Health endpoints: ${healthEndpoints.length ? healthEndpoints.join(', ') : '(none)'}`,
+  )
+
+  onSignals({ logger })
+
+  const app = express()
+  app.use(express.json())
+
+  if (corsOrigin) {
+    app.use(cors({ origin: corsOrigin }))
+  }
+
+  for (const ep of healthEndpoints) {
+    app.get(ep, (_req, res) => {
+      setResponseHeaders(res, headers)
+      res.send('ok')
+    })
+  }
+
+  // --- OAuth discovery & auth middleware (when auth is enabled) ---
+  if (auth) {
+    app.use(createDiscoveryRouter(auth, logger))
+    app.use(path, createAuthMiddleware(auth, logger))
+    logger.info(`  - Auth: enabled (issuer=${auth.issuer})`)
+  }
+
+  app.post(path, async (req, res) => {
+    try {
+      const server = new Server(
+        { name: 'platf-bridge', version: VERSION },
+        { capabilities: {} },
+      )
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      })
+
+      await server.connect(transport)
+      const child = spawn(stdioCmd, { shell: true })
+
+      const pendingRequestIds = new Set<string | number>()
+      let stderrOutput = ''
+
+      child.on('exit', (code, signal) => {
+        logger.error(`Child exited: code=${code}, signal=${signal}`)
+
+        // Include queued original message's ID if it was never sent to the child
+        if (pendingOriginalMessage && 'id' in pendingOriginalMessage && pendingOriginalMessage.id !== undefined) {
+          pendingRequestIds.add(pendingOriginalMessage.id as string | number)
+          pendingOriginalMessage = null
+        }
+
+        // Remove auto-init ID — the client doesn't expect a response for it
+        if (isAutoInitializing && initializeRequestId !== null) {
+          pendingRequestIds.delete(initializeRequestId)
+        }
+
+        // Send JSON-RPC error responses for all pending client requests
+        for (const id of pendingRequestIds) {
+          const detail = stderrOutput.trim().slice(0, 1000)
+          const message = detail
+            ? `Child process exited (code=${code}): ${detail}`
+            : `Child process exited unexpectedly (code=${code}, signal=${signal})`
+          try {
+            transport.send({
+              jsonrpc: '2.0',
+              error: { code: -32603, message },
+              id,
+            } as JSONRPCMessage)
+          } catch (e) {
+            logger.error(`Failed to send error response for request ${id}`, e)
+          }
+        }
+        pendingRequestIds.clear()
+
+        transport.close()
+      })
+
+      // --- Auto-initialization state ---
+      let isInitialized = false
+      let initializeRequestId: string | number | null = null
+      let isAutoInitializing = false
+      let pendingOriginalMessage: JSONRPCMessage | null = null
+
+      let buffer = ''
+      child.stdout.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString('utf8')
+        const lines = buffer.split(/\r?\n/)
+        buffer = lines.pop() ?? ''
+
+        for (const line of lines) {
+          if (!line.trim()) continue
+          try {
+            const jsonMsg = JSON.parse(line)
+            if ('id' in jsonMsg && jsonMsg.id !== undefined) {
+              pendingRequestIds.delete(jsonMsg.id)
+            }
+            logger.info('Child → HTTP:', line)
+
+            // Handle initialize response (auto or client-initiated)
+            if (initializeRequestId && jsonMsg.id === initializeRequestId) {
+              logger.info('Initialize response received')
+              isInitialized = true
+
+              if (isAutoInitializing) {
+                // Send initialized notification then the queued original message
+                const notification = createInitializedNotification()
+                logger.info(`HTTP → Child (initialized): ${JSON.stringify(notification)}`)
+                child.stdin.write(JSON.stringify(notification) + '\n')
+
+                if (pendingOriginalMessage) {
+                  logger.info(`HTTP → Child (original): ${JSON.stringify(pendingOriginalMessage)}`)
+                  child.stdin.write(JSON.stringify(pendingOriginalMessage) + '\n')
+                  pendingOriginalMessage = null
+                }
+
+                isAutoInitializing = false
+                initializeRequestId = null
+                return // don't forward auto-init response to client
+              }
+
+              initializeRequestId = null
+            }
+
+            try {
+              transport.send(jsonMsg)
+            } catch (e) {
+              logger.error('Failed to send to HTTP transport', e)
+            }
+          } catch {
+            logger.error(`Child non-JSON: ${line}`)
+          }
+        }
+      })
+
+      child.stderr.on('data', (chunk: Buffer) => {
+        const text = chunk.toString('utf8')
+        stderrOutput += text
+        logger.error(`Child stderr: ${text}`)
+      })
+
+      transport.onmessage = (msg: JSONRPCMessage) => {
+        logger.info(`HTTP → Child: ${JSON.stringify(msg)}`)
+
+        // Track client request IDs for error reporting on child exit
+        if ('id' in msg && msg.id !== undefined) {
+          pendingRequestIds.add(msg.id as string | number)
+        }
+
+        // Auto-initialize if the first message is not an initialize request
+        if (!isInitialized && !isInitializeRequest(msg)) {
+          pendingOriginalMessage = msg
+          initializeRequestId = `init_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`
+          isAutoInitializing = true
+
+          logger.info('Non-initialize message detected, sending auto-initialize first')
+          const initReq = createInitializeRequest(initializeRequestId, protocolVersion)
+          logger.info(`HTTP → Child (auto-init): ${JSON.stringify(initReq)}`)
+          child.stdin.write(JSON.stringify(initReq) + '\n')
+          return
+        }
+
+        // Track client-initiated initialize
+        if (isInitializeRequest(msg) && 'id' in msg && msg.id !== undefined) {
+          initializeRequestId = msg.id
+          isAutoInitializing = false
+          logger.info(`Tracking initialize request ID: ${msg.id}`)
+        }
+
+        child.stdin.write(JSON.stringify(msg) + '\n')
+      }
+
+      transport.onclose = () => {
+        logger.info('HTTP connection closed')
+        child.kill()
+      }
+
+      transport.onerror = (err) => {
+        logger.error('HTTP transport error:', err)
+        child.kill()
+      }
+
+      await transport.handleRequest(req, res, req.body)
+    } catch (error) {
+      logger.error('Error handling MCP request:', error)
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal server error' },
+          id: null,
+        })
+      }
+    }
+  })
+
+  app.get(path, (_req, res) => {
+    logger.info('Received GET — method not allowed in stateless mode')
+    res.writeHead(405).end(
+      JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed.' },
+        id: null,
+      }),
+    )
+  })
+
+  app.delete(path, (_req, res) => {
+    logger.info('Received DELETE — method not allowed in stateless mode')
+    res.writeHead(405).end(
+      JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed.' },
+        id: null,
+      }),
+    )
+  })
+
+  app.listen(port, () => {
+    logger.info(`Listening on port ${port}`)
+    logger.info(`Streamable HTTP endpoint: http://localhost:${port}${path}`)
+  })
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+import { getLogger, type LogLevel } from './lib/getLogger.js'
+import { parseCorsOrigin } from './lib/cors.js'
+import { parseHeaders } from './lib/headers.js'
+import { startStatelessBridge } from './gateways/statelessBridge.js'
+import { startStatefulBridge } from './gateways/statefulBridge.js'
+import type { AuthConfig } from './types.js'
+
+const argv = await yargs(hideBin(process.argv))
+  .scriptName('platf-bridge')
+  .usage('$0 — Stdio-to-Streamable HTTP bridge for MCP servers')
+  .option('stdio', {
+    type: 'string',
+    demandOption: true,
+    describe: 'Shell command that speaks MCP over stdio (stdin/stdout)',
+  })
+  .option('port', {
+    type: 'number',
+    default: 8000,
+    describe: 'HTTP port to listen on',
+  })
+  .option('path', {
+    type: 'string',
+    default: '/mcp',
+    describe: 'HTTP path for the Streamable HTTP endpoint',
+  })
+  .option('stateful', {
+    type: 'boolean',
+    default: false,
+    describe: 'Enable stateful mode (session-based, persistent child process per session)',
+  })
+  .option('sessionTimeout', {
+    type: 'number',
+    describe: 'Session inactivity timeout in milliseconds (stateful mode only)',
+  })
+  .option('protocolVersion', {
+    type: 'string',
+    default: '2025-03-26',
+    describe: 'MCP protocol version for auto-initialization (stateless mode)',
+  })
+  .option('logLevel', {
+    type: 'string',
+    choices: ['none', 'info', 'debug'] as const,
+    default: 'info',
+    describe: 'Log verbosity',
+  })
+  .option('cors', {
+    type: 'array',
+    describe: 'CORS origins to allow (omit for no CORS, pass * for all)',
+  })
+  .option('healthEndpoint', {
+    type: 'array',
+    string: true,
+    default: [] as string[],
+    describe: 'Path(s) that return 200 "ok" for health checks',
+  })
+  .option('header', {
+    type: 'array',
+    default: [] as (string | number)[],
+    describe: 'Additional response headers in "Key: Value" format',
+  })
+  .option('authIssuer', {
+    type: 'string',
+    describe: 'OAuth issuer URL (e.g. https://auth.platf.ai). Enables auth when set.',
+  })
+  .option('authClientId', {
+    type: 'string',
+    describe: 'OAuth client_id for this bridge instance (pre-registered with auth issuer)',
+  })
+  .strict()
+  .help()
+  .parse()
+
+const logger = getLogger(argv.logLevel as LogLevel)
+const corsOrigin = parseCorsOrigin(argv.cors as (string | number)[] | undefined)
+const headers = parseHeaders(argv.header, logger)
+
+// Build auth config (only when --authIssuer is provided)
+let auth: AuthConfig | null = null
+if (argv.authIssuer) {
+  if (!argv.authClientId) {
+    console.error('Error: --authClientId is required when --authIssuer is set')
+    process.exit(1)
+  }
+  auth = { issuer: argv.authIssuer.replace(/\/$/, ''), clientId: argv.authClientId }
+  logger.info(`  Auth: enabled (issuer=${auth.issuer}, clientId=${auth.clientId})`)
+} else {
+  logger.info('  Auth: disabled')
+}
+
+logger.info('platf-bridge starting...')
+logger.info(`  Mode: ${argv.stateful ? 'stateful' : 'stateless'}`)
+
+if (argv.stateful) {
+  await startStatefulBridge({
+    stdioCmd: argv.stdio,
+    port: argv.port,
+    path: argv.path,
+    logger,
+    corsOrigin,
+    healthEndpoints: argv.healthEndpoint,
+    headers,
+    sessionTimeout: argv.sessionTimeout ?? null,
+    auth,
+  })
+} else {
+  await startStatelessBridge({
+    stdioCmd: argv.stdio,
+    port: argv.port,
+    path: argv.path,
+    logger,
+    corsOrigin,
+    healthEndpoints: argv.healthEndpoint,
+    headers,
+    protocolVersion: argv.protocolVersion,
+    auth,
+  })
+}