@platf/bridge 0.0.15 → 0.0.17

package/src/gateways/statelessBridge.ts

@@ -1,19 +1,22 @@
-import express from 'express'
-import cors, { type CorsOptions } from 'cors'
-import { spawn } from 'child_process'
+/**
+ * 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.
+ */
+
 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 JSONRPCMessage, isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'
+import type { CorsOptions } from 'cors'
 import type { AuthConfig, Logger } from '../types.js'
+import { createApp, setResponseHeaders } from '../lib/express.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'
+import { spawnManagedChild } from '../lib/childProcess.js'
+import { createInitializeRequest, createInitializedNotification, generateAutoInitId } from '../lib/mcpMessages.js'
+import { VERSION, SERVER_NAME } from '../lib/config.js'
 
 export interface StatelessBridgeArgs {
   stdioCmd: string
@@ -27,225 +30,115 @@ export interface StatelessBridgeArgs {
   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.
+ * Start the stateless bridge server.
  */
 export async function startStatelessBridge(args: StatelessBridgeArgs) {
-  const {
-    stdioCmd,
-    port,
-    path,
-    logger,
-    corsOrigin,
-    healthEndpoints,
-    headers,
-    protocolVersion,
-    auth,
-  } = args
+  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(`[stateless] Starting ${SERVER_NAME}`)
   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)'}`,
-  )
+  logger.info(`  - Headers: ${Object.keys(headers).length ? JSON.stringify(headers) : '(none)'}`)
 
   onSignals({ logger })
 
-  const app = express()
-  app.set('trust proxy', true)
-  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})`)
-  }
+  const app = createApp({
+    logger,
+    corsOrigin,
+    healthEndpoints,
+    headers,
+    auth,
+    mcpPath: path,
+  })
 
+  // POST handler — spawn child, proxy messages
   app.post(path, async (req, res) => {
     try {
-      const server = new Server(
-        { name: 'platf-bridge', version: VERSION },
-        { capabilities: {} },
-      )
-      const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: undefined,
-      })
-
+      const server = new Server({ name: SERVER_NAME, 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 ---
+      // 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')
+      const managedChild = spawnManagedChild(stdioCmd, logger, {
+        onMessage: (msg) => {
+          // Handle initialize response (auto or client-initiated)
+          if (initializeRequestId && 'id' in msg && msg.id === initializeRequestId) {
+            logger.info('[stateless] Initialize response received')
+            isInitialized = true
 
-                if (pendingOriginalMessage) {
-                  logger.info(`HTTP → Child (original): ${JSON.stringify(pendingOriginalMessage)}`)
-                  child.stdin.write(JSON.stringify(pendingOriginalMessage) + '\n')
-                  pendingOriginalMessage = null
-                }
+            if (isAutoInitializing) {
+              // Send initialized notification then the queued original message
+              managedChild.send(createInitializedNotification())
 
-                isAutoInitializing = false
-                initializeRequestId = null
-                return // don't forward auto-init response to client
+              if (pendingOriginalMessage) {
+                managedChild.send(pendingOriginalMessage)
+                pendingOriginalMessage = null
               }
 
+              isAutoInitializing = false
               initializeRequestId = null
+              return // don't forward auto-init response to client
             }
 
-            try {
-              transport.send(jsonMsg)
-            } catch (e) {
-              logger.error('Failed to send to HTTP transport', e)
-            }
-          } catch {
-            logger.error(`Child non-JSON: ${line}`)
+            initializeRequestId = null
+          }
+
+          transport.send(msg).catch((e) => {
+            logger.error('[stateless] Failed to send to HTTP transport', e)
+          })
+        },
+
+        onExit: (code, signal, stderrOutput) => {
+          // Include queued original message's ID if never sent
+          if (pendingOriginalMessage && 'id' in pendingOriginalMessage && pendingOriginalMessage.id !== undefined) {
+            managedChild.trackRequest(pendingOriginalMessage.id as string | number)
+            pendingOriginalMessage = null
+          }
+
+          // Remove auto-init ID — client doesn't expect a response for it
+          if (isAutoInitializing && initializeRequestId !== null) {
+            managedChild.completeRequest(initializeRequestId)
           }
-        }
-      })
 
-      child.stderr.on('data', (chunk: Buffer) => {
-        const text = chunk.toString('utf8')
-        stderrOutput += text
-        logger.error(`Child stderr: ${text}`)
+          // Send error responses for all pending requests
+          for (const id of managedChild.getPendingRequests()) {
+            const detail = stderrOutput.trim().slice(0, 1000)
+            const message = detail
+              ? `Child process exited (code=${code}): ${detail}`
+              : `Child process exited unexpectedly (code=${code}, signal=${signal})`
+            transport.send({
+              jsonrpc: '2.0',
+              error: { code: -32603, message },
+              id,
+            } as JSONRPCMessage).catch(() => {})
+          }
+
+          transport.close()
+        },
       })
 
       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)
+          managedChild.trackRequest(msg.id as string | number)
         }
 
-        // Auto-initialize if the first message is not an initialize request
+        // Auto-initialize if first message is not an initialize request
         if (!isInitialized && !isInitializeRequest(msg)) {
           pendingOriginalMessage = msg
-          initializeRequestId = `init_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`
+          initializeRequestId = generateAutoInitId()
           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')
+          logger.info('[stateless] Non-initialize message detected, sending auto-initialize first')
+          managedChild.send(createInitializeRequest(initializeRequestId, protocolVersion))
           return
         }
 
@@ -253,25 +146,25 @@ export async function startStatelessBridge(args: StatelessBridgeArgs) {
         if (isInitializeRequest(msg) && 'id' in msg && msg.id !== undefined) {
           initializeRequestId = msg.id
           isAutoInitializing = false
-          logger.info(`Tracking initialize request ID: ${msg.id}`)
+          logger.info(`[stateless] Tracking initialize request ID: ${msg.id}`)
         }
 
-        child.stdin.write(JSON.stringify(msg) + '\n')
+        managedChild.send(msg)
       }
 
       transport.onclose = () => {
-        logger.info('HTTP connection closed')
-        child.kill()
+        logger.info('[stateless] HTTP connection closed')
+        managedChild.kill()
       }
 
       transport.onerror = (err) => {
-        logger.error('HTTP transport error:', err)
-        child.kill()
+        logger.error('[stateless] HTTP transport error:', err)
+        managedChild.kill()
       }
 
       await transport.handleRequest(req, res, req.body)
     } catch (error) {
-      logger.error('Error handling MCP request:', error)
+      logger.error('[stateless] Error handling MCP request:', error)
       if (!res.headersSent) {
         res.status(500).json({
           jsonrpc: '2.0',
@@ -282,27 +175,16 @@ export async function startStatelessBridge(args: StatelessBridgeArgs) {
     }
   })
 
-  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,
-      }),
-    )
-  })
+  // GET/DELETE not allowed in stateless mode
+  const methodNotAllowed = (_req: any, res: any) => {
+    res.writeHead(405).end(JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Method not allowed.' },
+      id: null,
+    }))
+  }
+  app.get(path, methodNotAllowed)
+  app.delete(path, methodNotAllowed)
 
   app.listen(port, () => {
     logger.info(`Listening on port ${port}`)

package/src/index.ts

@@ -2,12 +2,12 @@
 
 import yargs from 'yargs'
 import { hideBin } from 'yargs/helpers'
-import { getLogger, type LogLevel } from './lib/getLogger.js'
+import { getLogger } 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'
+import type { AuthConfig, LogLevel } from './types.js'
 
 const argv = await yargs(hideBin(process.argv))
   .scriptName('platf-bridge')

package/src/lib/childProcess.ts

@@ -0,0 +1,120 @@
+/**
+ * Child process management for stdio-based MCP servers.
+ *
+ * Handles spawning child processes, parsing JSON-RPC messages from stdout,
+ * and writing messages to stdin.
+ */
+
+import { spawn, type ChildProcess } from 'child_process'
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js'
+import type { Logger } from '../types.js'
+
+export interface ChildProcessCallbacks {
+  /** Called when a JSON-RPC message is received from the child */
+  onMessage: (msg: JSONRPCMessage) => void
+  /** Called when the child process exits */
+  onExit: (code: number | null, signal: string | null, stderrOutput: string) => void
+  /** Called when there's an error spawning or communicating with the child */
+  onError?: (err: Error) => void
+}
+
+export interface ManagedChildProcess {
+  /** The underlying child process */
+  child: ChildProcess
+  /** Send a JSON-RPC message to the child's stdin */
+  send: (msg: JSONRPCMessage) => boolean
+  /** Kill the child process */
+  kill: () => void
+  /** Track a request ID as pending (for error reporting on exit) */
+  trackRequest: (id: string | number) => void
+  /** Mark a request ID as completed */
+  completeRequest: (id: string | number) => void
+  /** Get all pending request IDs */
+  getPendingRequests: () => Set<string | number>
+}
+
+/**
+ * Spawn a child process and set up JSON-RPC message handling.
+ * 
+ * The child is expected to speak JSON-RPC over stdio (one message per line).
+ */
+export function spawnManagedChild(
+  command: string,
+  logger: Logger,
+  callbacks: ChildProcessCallbacks,
+): ManagedChildProcess {
+  const pendingRequestIds = new Set<string | number>()
+  let stderrOutput = ''
+  let buffer = ''
+
+  const child = spawn(command, { shell: true, stdio: ['pipe', 'pipe', 'pipe'] })
+
+  logger.info(`[child] Spawned process, pid=${child.pid}`)
+
+  child.on('spawn', () => {
+    logger.info(`[child] spawn event fired, pid=${child.pid}`)
+  })
+
+  child.on('error', (err) => {
+    logger.error(`[child] error event: ${err.message}`)
+    callbacks.onError?.(err)
+  })
+
+  child.on('exit', (code, signal) => {
+    logger.info(`[child] exited: code=${code}, signal=${signal}`)
+    callbacks.onExit(code, signal, stderrOutput)
+  })
+
+  child.stdout.on('data', (chunk: Buffer) => {
+    const chunkStr = chunk.toString('utf8')
+    logger.info(`[child] stdout received ${chunk.length} bytes`)
+    buffer += chunkStr
+
+    const lines = buffer.split(/\r?\n/)
+    buffer = lines.pop() ?? ''
+
+    for (const line of lines) {
+      if (!line.trim()) continue
+      try {
+        const jsonMsg = JSON.parse(line) as JSONRPCMessage
+        // Auto-complete request tracking for responses
+        if ('id' in jsonMsg && jsonMsg.id !== undefined) {
+          pendingRequestIds.delete(jsonMsg.id)
+        }
+        logger.info(`[child] → message: ${line.slice(0, 200)}${line.length > 200 ? '...' : ''}`)
+        callbacks.onMessage(jsonMsg)
+      } catch {
+        logger.error(`[child] non-JSON output: ${line}`)
+      }
+    }
+  })
+
+  child.stderr.on('data', (chunk: Buffer) => {
+    const text = chunk.toString('utf8')
+    stderrOutput += text
+    logger.error(`[child] stderr: ${text}`)
+  })
+
+  child.stdin.on('error', (err) => {
+    logger.error(`[child] stdin error: ${err.message}`)
+  })
+
+  return {
+    child,
+    send: (msg: JSONRPCMessage) => {
+      const payload = JSON.stringify(msg) + '\n'
+      logger.info(`[child] ← message: ${JSON.stringify(msg).slice(0, 200)}`)
+      return child.stdin.write(payload)
+    },
+    kill: () => {
+      child.kill()
+    },
+    trackRequest: (id: string | number) => {
+      pendingRequestIds.add(id)
+    },
+    completeRequest: (id: string | number) => {
+      pendingRequestIds.delete(id)
+    },
+    getPendingRequests: () => pendingRequestIds,
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,9 @@
+/** Shared configuration constants */
+
+export const VERSION = '1.0.0'
+
+/** Default MCP protocol version for auto-initialization */
+export const DEFAULT_PROTOCOL_VERSION = '2025-03-26'
+
+/** Bridge server name used in MCP handshakes */
+export const SERVER_NAME = 'platf-bridge'

package/src/lib/discoveryRoutes.ts

@@ -6,6 +6,8 @@
  *  - GET  /.well-known/oauth-authorization-server[/*] (RFC 8414 — proxied from issuer)
  *  - POST /oauth/register                             (Pseudo-DCR — RFC 7591)
  *
+ * OAuth proxy routes (/oauth/authorize, /oauth/token, /jwks) are in oauthProxy.ts.
+ *
  * These endpoints are unauthenticated — they must be accessible to
  * any client performing OAuth discovery before obtaining a token.
  */
@@ -87,10 +89,15 @@ export function createDiscoveryRouter(auth: AuthConfig, logger: Logger): Router
 
       const metadata = (await upstream.json()) as Record<string, unknown>
 
-      // Patch registration_endpoint to point to our pseudo-DCR
+      // Patch all OAuth endpoints to point to our proxy
       const scheme = req.protocol
       const host = req.get('host')
-      metadata.registration_endpoint = `${scheme}://${host}/oauth/register`
+      const bridgeOrigin = `${scheme}://${host}`
+      metadata.issuer = bridgeOrigin
+      metadata.authorization_endpoint = `${bridgeOrigin}/oauth/authorize`
+      metadata.token_endpoint = `${bridgeOrigin}/oauth/token`
+      metadata.registration_endpoint = `${bridgeOrigin}/oauth/register`
+      metadata.jwks_uri = `${bridgeOrigin}/jwks`
 
       res.json(metadata)
     } catch (err: any) {
@@ -120,71 +127,5 @@ export function createDiscoveryRouter(auth: AuthConfig, logger: Logger): Router
     })
   })
 
-  /**
-   * OAuth Authorization Endpoint — Redirect to upstream
-   *
-   * Since the bridge advertises itself as the authorization_server,
-   * clients will attempt to call /oauth/authorize here. We redirect
-   * to the upstream auth server, preserving all query parameters.
-   */
-  router.get('/oauth/authorize', (req: Request, res: Response) => {
-    const upstreamUrl = new URL(`${auth.issuer}/oauth/authorize`)
-    // Copy all query params to upstream
-    for (const [key, value] of Object.entries(req.query)) {
-      if (typeof value === 'string') {
-        upstreamUrl.searchParams.set(key, value)
-      }
-    }
-    logger.info(`[discovery] Redirecting /oauth/authorize to ${upstreamUrl.toString().slice(0, 100)}...`)
-    res.redirect(upstreamUrl.toString())
-  })
-
-  /**
-   * OAuth Token Endpoint — Proxy to upstream
-   *
-   * Proxies token exchange requests to the upstream auth server.
-   */
-  router.post('/oauth/token', async (req: Request, res: Response) => {
-    try {
-      const upstreamUrl = `${auth.issuer}/oauth/token`
-      logger.info('[discovery] Proxying /oauth/token to upstream')
-
-      const upstreamRes = await fetch(upstreamUrl, {
-        method: 'POST',
-        headers: {
-          'Content-Type': req.get('Content-Type') || 'application/x-www-form-urlencoded',
-        },
-        body: req.get('Content-Type')?.includes('application/json')
-          ? JSON.stringify(req.body)
-          : new URLSearchParams(req.body as Record<string, string>).toString(),
-      })
-
-      const data = await upstreamRes.text()
-      res.status(upstreamRes.status)
-      res.set('Content-Type', upstreamRes.headers.get('Content-Type') || 'application/json')
-      res.send(data)
-    } catch (err: any) {
-      logger.error('[discovery] Error proxying /oauth/token:', err.message ?? err)
-      res.status(502).json({ error: 'upstream_error' })
-    }
-  })
-
-  /**
-   * JWKS Endpoint — Proxy to upstream
-   *
-   * Proxies JSON Web Key Set requests for token verification.
-   */
-  router.get('/jwks', async (req: Request, res: Response) => {
-    try {
-      const upstreamUrl = `${auth.issuer}/jwks`
-      const upstreamRes = await fetch(upstreamUrl)
-      const data = await upstreamRes.json()
-      res.json(data)
-    } catch (err: any) {
-      logger.error('[discovery] Error proxying /jwks:', err.message ?? err)
-      res.status(502).json({ error: 'upstream_error' })
-    }
-  })
-
   return router
 }