@onmars/lunar-mcp 0.6.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onmars/lunar-mcp",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -11,9 +11,7 @@
     "src/",
     "LICENSE"
   ],
-  "dependencies": {
-    "@onmars/lunar-core": "^0.6.0"
-  },
+  "dependencies": {},
   "description": "MCP (Model Context Protocol) client for Lunar",
   "author": "onMars Tech",
   "license": "MIT",

package/src/__tests__/connection.test.ts

@@ -53,7 +53,7 @@ function createMockProcess() {
         result = {
           protocolVersion: '2025-11-25',
           capabilities: { tools: { listChanged: false } },
-          serverInfo: { name: 'mock-engram', version: '0.1.0' },
+          serverInfo: { name: 'mock-mcp-server', version: '0.1.0' },
         }
       } else if (method === 'tools/list') {
         result = {
@@ -187,7 +187,7 @@ describe('MCPConnection', () => {
     conn = new MCPConnection(mockConfig())
     await conn.connect()
     expect(conn.state).toBe('ready')
-    expect(conn.serverInfo?.name).toBe('mock-engram')
+    expect(conn.serverInfo?.name).toBe('mock-mcp-server')
     expect(conn.serverInfo?.version).toBe('0.1.0')
   })
 
@@ -271,7 +271,7 @@ describe('MCPRegistry', () => {
     expect(status).toHaveLength(1)
     expect(status[0].id).toBe('server1')
     expect(status[0].state).toBe('ready')
-    expect(status[0].serverName).toBe('mock-engram')
+    expect(status[0].serverName).toBe('mock-mcp-server')
     expect(status[0].toolCount).toBe(3)
   })
 

package/src/__tests__/mock-mcp-server.ts

@@ -60,7 +60,7 @@ rl.on('line', (line) => {
       respond(msg.id, {
         protocolVersion: '2025-11-25',
         capabilities: { tools: { listChanged: false } },
-        serverInfo: { name: 'mock-engram', version: '0.1.0' },
+        serverInfo: { name: 'mock-mcp-server', version: '0.1.0' },
       })
       return
     }

package/src/index.ts

@@ -10,24 +10,35 @@
  *
  * const registry = new MCPRegistry()
  *
- * // Connect to Engram
+ * // Connect to any MCP server (stdio)
  * await registry.connect({
- *   id: 'engram',
- *   command: 'engram mcp',
- *   role: 'memory',
+ *   id: 'my-tools',
+ *   command: 'my-mcp-server',
+ *   role: 'tools',
  * })
  *
  * // List all tools
  * const tools = registry.listTools()
  *
  * // Call a tool (auto-routes to correct server)
- * await registry.callTool('mem_search', { query: 'auth middleware' })
+ * await registry.callTool('search', { query: 'auth middleware' })
  * ```
  */
 
 // Core
-export { type ConnectionState, MCPConnection } from './lib/connection'
+export { type ConnectionState, MCPConnection, resolveTransportConfig } from './lib/connection'
 export { type MCPConnectionStatus, MCPRegistry } from './lib/registry'
+export {
+  HttpTransport,
+  type HttpTransportOptions,
+  type InboundMessage,
+  type MCPTransport,
+  type OutboundMessage,
+  SseTransport,
+  type SseTransportOptions,
+  StdioTransport,
+  type StdioTransportOptions,
+} from './lib/transports'
 
 // Types
 export type {
@@ -40,8 +51,13 @@ export type {
   JsonRpcNotification,
   JsonRpcRequest,
   JsonRpcResponse,
+  MCPHttpConfig,
+  MCPSseConfig,
   MCPServerConfig,
+  MCPStdioConfig,
   MCPTool,
+  MCPTransportConfig,
+  MCPTransportKind,
   ServerCapabilities,
   ServerInfo,
   ToolCallParams,

package/src/lib/connection.ts

@@ -1,20 +1,25 @@
 /**
- * MCPConnection — Single connection to an MCP server via stdio
+ * MCPConnection — Single connection to an MCP server
  *
  * Manages:
- * - Subprocess lifecycle (spawn, restart, shutdown)
- * - JSON-RPC 2.0 protocol over stdin/stdout
+ * - Transport lifecycle (stdio subprocess, HTTP, SSE)
+ * - JSON-RPC 2.0 request/response correlation via message IDs
  * - MCP handshake (initialize → initialized)
  * - Tool discovery and invocation
- * - Request/response correlation via message IDs
- * - Newline-delimited JSON framing
  *
- * Each MCPConnection wraps exactly one subprocess running an MCP server.
- * The MCPRegistry manages multiple connections.
+ * The actual IO is delegated to an MCPTransport (stdio/http/sse).
+ * MCPRegistry manages multiple MCPConnection instances.
  */
 
-import { type ChildProcess, spawn } from 'node:child_process'
 import { EventEmitter } from 'node:events'
+import {
+  HttpTransport,
+  type MCPTransport,
+  type OutboundMessage,
+  type InboundMessage,
+  SseTransport,
+  StdioTransport,
+} from './transports'
 import type {
   InitializeResult,
   JsonRpcNotification,
@@ -22,6 +27,7 @@ import type {
   JsonRpcResponse,
   MCPServerConfig,
   MCPTool,
+  MCPTransportConfig,
   ServerCapabilities,
   ServerInfo,
   ToolCallResult,
@@ -29,10 +35,48 @@ import type {
 
 export type ConnectionState = 'disconnected' | 'connecting' | 'ready' | 'error'
 
+/**
+ * Resolve a transport-config from an MCPServerConfig.
+ * Accepts the new discriminated `transport` field or falls back to the
+ * legacy stdio shorthand (`command` + `args`).
+ */
+export function resolveTransportConfig(config: MCPServerConfig): MCPTransportConfig {
+  if (config.transport) return config.transport
+  if (config.command) {
+    return {
+      transport: 'stdio',
+      command: config.command,
+      args: config.args,
+      cwd: config.cwd,
+      env: config.env,
+    }
+  }
+  throw new Error(
+    `MCPConnection "${config.id}": no transport or command configured`,
+  )
+}
+
+function buildTransport(config: MCPTransportConfig): MCPTransport {
+  switch (config.transport) {
+    case 'stdio':
+      return new StdioTransport({
+        command: config.command,
+        args: config.args,
+        cwd: config.cwd,
+        env: config.env,
+      })
+    case 'http':
+      return new HttpTransport({ url: config.url, headers: config.headers })
+    case 'sse':
+      return new SseTransport({ url: config.url, headers: config.headers })
+  }
+}
+
 export class MCPConnection extends EventEmitter {
   readonly id: string
   private config: MCPServerConfig
-  private process: ChildProcess | null = null
+  private transport: MCPTransport | null = null
+  private transportKind: 'stdio' | 'http' | 'sse' = 'stdio'
   private nextId = 1
   private pending = new Map<
     number | string,
@@ -42,7 +86,6 @@ export class MCPConnection extends EventEmitter {
       timer: ReturnType<typeof setTimeout>
     }
   >()
-  private buffer = ''
   private _state: ConnectionState = 'disconnected'
   private _tools: MCPTool[] = []
   private _serverInfo: ServerInfo | null = null
@@ -60,6 +103,10 @@ export class MCPConnection extends EventEmitter {
   get capabilities(): ServerCapabilities | null {
     return this._capabilities
   }
+  /** Which transport is in use (for status output / tests). */
+  get transportType(): 'stdio' | 'http' | 'sse' {
+    return this.transportKind
+  }
 
   constructor(config: MCPServerConfig) {
     super()
@@ -68,7 +115,7 @@ export class MCPConnection extends EventEmitter {
   }
 
   /**
-   * Spawn the MCP server subprocess and perform the MCP handshake.
+   * Open the transport and perform the MCP handshake.
    * After this resolves, the connection is ready for tool calls.
    */
   async connect(): Promise<void> {
@@ -76,66 +123,66 @@ export class MCPConnection extends EventEmitter {
     this._state = 'connecting'
 
     try {
-      // 1. Spawn subprocess
-      const [cmd, ...defaultArgs] = this.config.command.split(' ')
-      const args = [...defaultArgs, ...(this.config.args || [])]
-
-      try {
-        this.process = spawn(cmd, args, {
-          stdio: ['pipe', 'pipe', 'pipe'],
-          cwd: this.config.cwd,
-          env: { ...process.env, ...this.config.env },
-        })
-      } catch (spawnError) {
-        this._state = 'error'
-        throw spawnError
-      }
-
-      // Handle subprocess events
-      this.process.on('exit', (code, signal) => {
+      const transportConfig = resolveTransportConfig(this.config)
+      this.transportKind = transportConfig.transport
+      this.transport = buildTransport(transportConfig)
+
+      // Forward transport events
+      this.transport.on('message', (msg) => this.handleMessage(msg))
+      this.transport.on('log', (line) => this.emit('log', line))
+      this.transport.on('exit', (info) => {
         this._state = 'disconnected'
-        this.rejectAllPending(new Error(`MCP server exited (code=${code}, signal=${signal})`))
-        this.emit('exit', { code, signal })
+        this.rejectAllPending(
+          new Error(`MCP transport exited (code=${info.code}, signal=${info.signal})`),
+        )
+        this.emit('exit', info)
       })
-
-      this.process.on('error', (err) => {
+      this.transport.on('error', (err) => {
         this._state = 'error'
         this.rejectAllPending(err)
         this.emit('error', err)
       })
 
-      // stderr → log (MCP servers may emit logs on stderr)
-      this.process.stderr?.on('data', (chunk: Buffer) => {
-        this.emit('log', chunk.toString())
-      })
+      await this.transport.start()
 
-      // stdout → JSON-RPC message parsing
-      this.process.stdout?.on('data', (chunk: Buffer) => {
-        this.buffer += chunk.toString()
-        this.processBuffer()
+      // Race the MCP handshake against early transport failure so broken
+      // binaries / unreachable URLs surface instantly instead of timing
+      // out at the request level.
+      const earlyFailure = new Promise<never>((_, reject) => {
+        const fail = (err: Error) => {
+          this.transport?.off('error', fail)
+          this.transport?.off('exit', onExit)
+          reject(err)
+        }
+        const onExit = () => fail(new Error(`transport exited before handshake completed`))
+        this.transport?.once('error', fail)
+        this.transport?.once('exit', onExit)
       })
 
-      // 2. MCP handshake: initialize
-      const initResult = (await this.request(
-        'initialize',
-        {
-          protocolVersion: '2025-11-25',
-          capabilities: {},
-          clientInfo: {
-            name: 'lunar',
-            version: '0.2.0',
+      // MCP handshake: initialize
+      const initResult = (await Promise.race([
+        this.request(
+          'initialize',
+          {
+            protocolVersion: '2025-11-25',
+            capabilities: {},
+            clientInfo: {
+              name: 'lunar',
+              version: '0.7.0',
+            },
           },
-        },
-        this.config.timeoutMs || 10000,
-      )) as InitializeResult
+          this.config.timeoutMs ?? 10000,
+        ),
+        earlyFailure,
+      ])) as InitializeResult
 
       this._serverInfo = initResult.serverInfo
       this._capabilities = initResult.capabilities
 
-      // 3. Send initialized notification
+      // Send initialized notification
       this.notify('notifications/initialized')
 
-      // 4. Discover tools
+      // Discover tools
       if (initResult.capabilities?.tools) {
         const toolsResult = (await this.request('tools/list', {})) as { tools: MCPTool[] }
         this._tools = toolsResult.tools || []
@@ -145,10 +192,11 @@ export class MCPConnection extends EventEmitter {
       this.emit('ready', {
         serverInfo: this._serverInfo,
         tools: this._tools.length,
+        transport: this.transportKind,
       })
     } catch (err) {
       this._state = 'error'
-      this.kill()
+      await this.safeStopTransport()
       throw err
     }
   }
@@ -215,55 +263,33 @@ export class MCPConnection extends EventEmitter {
   }
 
   /**
-   * Write a JSON-RPC message to the subprocess stdin.
-   * MCP uses newline-delimited JSON over stdio.
+   * Write a JSON-RPC message to the underlying transport.
    */
-  private send(message: JsonRpcRequest | JsonRpcNotification): void {
-    if (!this.process?.stdin?.writable) {
-      throw new Error(`MCP connection "${this.id}" stdin not writable`)
-    }
-    const json = JSON.stringify(message)
-    this.process.stdin.write(json + '\n')
-  }
-
-  /**
-   * Process buffered stdout data, extracting complete JSON-RPC messages.
-   * MCP uses newline-delimited JSON (one message per line).
-   */
-  private processBuffer(): void {
-    const lines = this.buffer.split('\n')
-    // Keep the last incomplete line in the buffer
-    this.buffer = lines.pop() || ''
-
-    for (const line of lines) {
-      const trimmed = line.trim()
-      if (!trimmed) continue
-
-      try {
-        const message = JSON.parse(trimmed)
-        this.handleMessage(message)
-      } catch {
-        // Non-JSON output (e.g., startup messages) — ignore
-        this.emit('log', `[non-json] ${trimmed}`)
-      }
+  private send(message: OutboundMessage): void {
+    if (!this.transport) {
+      throw new Error(`MCP connection "${this.id}" transport not open`)
     }
+    this.transport.send(message)
   }
 
   /**
    * Handle an incoming JSON-RPC message (response or server notification).
    */
-  private handleMessage(message: JsonRpcResponse | JsonRpcNotification): void {
+  private handleMessage(message: InboundMessage): void {
     // Response to a pending request
     if ('id' in message && message.id != null) {
-      const pending = this.pending.get(message.id)
+      const response = message as JsonRpcResponse
+      const pending = this.pending.get(response.id)
       if (pending) {
-        this.pending.delete(message.id)
+        this.pending.delete(response.id)
         clearTimeout(pending.timer)
 
-        if (message.error) {
-          pending.reject(new Error(`MCP error [${message.error.code}]: ${message.error.message}`))
+        if (response.error) {
+          pending.reject(
+            new Error(`MCP error [${response.error.code}]: ${response.error.message}`),
+          )
         } else {
-          pending.resolve(message.result)
+          pending.resolve(response.result)
         }
       }
       return
@@ -271,9 +297,10 @@ export class MCPConnection extends EventEmitter {
 
     // Server-initiated notification
     if ('method' in message) {
+      const note = message as JsonRpcNotification
       this.emit('notification', {
-        method: message.method,
-        params: message.params,
+        method: note.method,
+        params: note.params,
       })
     }
   }
@@ -290,55 +317,39 @@ export class MCPConnection extends EventEmitter {
   }
 
   /**
-   * Graceful shutdown: close stdin, wait, SIGTERM, SIGKILL.
+   * Graceful shutdown.
    */
   async disconnect(): Promise<void> {
-    if (!this.process) return
-
-    return new Promise<void>((resolve) => {
-      const proc = this.process!
-      let resolved = false
-
-      const done = () => {
-        if (!resolved) {
-          resolved = true
-          this.process = null
-          this._state = 'disconnected'
-          this._tools = []
-          resolve()
-        }
-      }
-
-      proc.on('exit', done)
-
-      // Step 1: Close stdin
-      proc.stdin?.end()
-
-      // Step 2: SIGTERM after 2s
-      setTimeout(() => {
-        if (!resolved) proc.kill('SIGTERM')
-      }, 2000)
-
-      // Step 3: SIGKILL after 5s
-      setTimeout(() => {
-        if (!resolved) {
-          proc.kill('SIGKILL')
-          done()
-        }
-      }, 5000)
-    })
+    if (!this.transport) return
+    await this.safeStopTransport()
+    this._state = 'disconnected'
+    this._tools = []
   }
 
   /**
-   * Force kill the subprocess immediately.
+   * Force close the transport immediately (stdio → SIGKILL).
    */
   kill(): void {
-    if (this.process) {
-      this.process.kill('SIGKILL')
-      this.process = null
-      this._state = 'disconnected'
-      this._tools = []
-      this.rejectAllPending(new Error('Connection killed'))
+    if (!this.transport) return
+    if (this.transport instanceof StdioTransport) {
+      this.transport.kill()
+    } else {
+      void this.transport.stop().catch(() => {})
+    }
+    this.transport = null
+    this._state = 'disconnected'
+    this._tools = []
+    this.rejectAllPending(new Error('Connection killed'))
+  }
+
+  private async safeStopTransport(): Promise<void> {
+    if (!this.transport) return
+    const t = this.transport
+    this.transport = null
+    try {
+      await t.stop()
+    } catch {
+      // ignore — we're already in teardown
     }
   }
 }

package/src/lib/registry.ts

@@ -21,6 +21,7 @@ export interface MCPConnectionStatus {
   serverVersion?: string
   toolCount: number
   role: string
+  transport: 'stdio' | 'http' | 'sse'
 }
 
 export class MCPRegistry extends EventEmitter {
@@ -190,6 +191,7 @@ export class MCPRegistry extends EventEmitter {
       serverVersion: conn.serverInfo?.version,
       toolCount: conn.tools.length,
       role: this.configs.get(id)?.role || 'tools',
+      transport: conn.transportType,
     }))
   }
 

package/src/lib/transports.ts

@@ -0,0 +1,485 @@
+/**
+ * MCP transports — pluggable IO layers for MCPConnection.
+ *
+ * Each transport exposes the same minimal surface:
+ *   - start(): open the underlying channel (spawn process / open stream).
+ *   - send(msg): write one JSON-RPC message.
+ *   - stop(): graceful shutdown.
+ *
+ * Incoming messages are delivered via the `message` event (one per JSON-RPC
+ * frame). Protocol-level bookkeeping (id correlation, initialize handshake,
+ * tool routing) lives in MCPConnection.
+ *
+ * Implementations here are intentionally dependency-free — they rely only
+ * on the Bun / node:* built-ins, so the `@onmars/lunar-mcp` package can be
+ * installed without pulling the official MCP SDK. When richer OAuth flows
+ * land in Phase 2, a separate transport can be added without touching
+ * MCPConnection.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import type { JsonRpcNotification, JsonRpcRequest, JsonRpcResponse } from './types'
+
+export type OutboundMessage = JsonRpcRequest | JsonRpcNotification
+export type InboundMessage = JsonRpcResponse | JsonRpcNotification
+
+export interface TransportEvents {
+  message: [InboundMessage]
+  log: [string]
+  exit: [{ code: number | null; signal: string | null }]
+  error: [Error]
+}
+
+export interface MCPTransport extends EventEmitter {
+  readonly kind: 'stdio' | 'http' | 'sse'
+  start(): Promise<void>
+  send(message: OutboundMessage): void
+  stop(): Promise<void>
+}
+
+// ════════════════════════════════════════════════════════════
+// stdio transport — subprocess, newline-delimited JSON-RPC
+// ════════════════════════════════════════════════════════════
+
+export interface StdioTransportOptions {
+  command: string
+  args?: string[]
+  cwd?: string
+  env?: Record<string, string>
+}
+
+export class StdioTransport extends EventEmitter implements MCPTransport {
+  readonly kind = 'stdio' as const
+  private proc: ChildProcess | null = null
+  private buffer = ''
+  private procExited = false
+
+  constructor(private readonly opts: StdioTransportOptions) {
+    super()
+  }
+
+  async start(): Promise<void> {
+    const [cmd, ...defaultArgs] = this.opts.command.split(' ')
+    const args = [...defaultArgs, ...(this.opts.args ?? [])]
+
+    this.proc = spawn(cmd, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: this.opts.cwd,
+      env: { ...process.env, ...this.opts.env },
+    })
+
+    const emitExit = (code: number | null, signal: string | null) => {
+      if (this.procExited) return
+      this.procExited = true
+      this.emit('exit', { code, signal })
+    }
+
+    this.proc.on('exit', (code, signal) => {
+      emitExit(code, signal)
+    })
+    this.proc.on('error', (err) => {
+      // spawn errors (e.g., ENOENT for missing binary) don't emit `exit`
+      // on their own. Surface the error AND mark the transport exited so
+      // downstream stop() doesn't wait forever.
+      this.emit('error', err)
+      emitExit(null, null)
+    })
+    this.proc.stderr?.on('data', (chunk: Buffer) => {
+      this.emit('log', chunk.toString())
+    })
+    this.proc.stdout?.on('data', (chunk: Buffer) => {
+      this.buffer += chunk.toString()
+      this.drain()
+    })
+  }
+
+  send(message: OutboundMessage): void {
+    if (!this.proc?.stdin?.writable) {
+      throw new Error('StdioTransport: stdin not writable')
+    }
+    this.proc.stdin.write(`${JSON.stringify(message)}\n`)
+  }
+
+  async stop(): Promise<void> {
+    if (!this.proc) return
+    const proc = this.proc
+    this.proc = null
+
+    // If the child already exited (or failed to spawn), bail out fast.
+    if (this.procExited || proc.exitCode !== null || proc.signalCode !== null) return
+
+    return new Promise<void>((resolveStop) => {
+      let settled = false
+      const done = () => {
+        if (!settled) {
+          settled = true
+          resolveStop()
+        }
+      }
+      proc.on('exit', done)
+      proc.on('error', () => {
+        // spawn error (ENOENT etc) — treat as done, don't wait 5s
+        done()
+      })
+
+      // If the spawn already failed asynchronously between our `new Promise`
+      // and this point, `procExited` is now true. Short-circuit.
+      if (this.procExited) {
+        done()
+        return
+      }
+
+      try {
+        proc.stdin?.end()
+      } catch {
+        // stdin may already be closed for failed spawns
+      }
+
+      // Poll on next tick — spawn errors tend to fire immediately after
+      // the synchronous spawn() call, so a single microtask check avoids
+      // the full 2s SIGTERM wait for broken binaries.
+      queueMicrotask(() => {
+        if (!settled && this.procExited) done()
+      })
+
+      setTimeout(() => {
+        if (!settled) {
+          try {
+            proc.kill('SIGTERM')
+          } catch {}
+        }
+      }, 2000)
+      setTimeout(() => {
+        if (!settled) {
+          try {
+            proc.kill('SIGKILL')
+          } catch {}
+          done()
+        }
+      }, 5000)
+    })
+  }
+
+  /**
+   * Force-kill the subprocess immediately (used on hard errors).
+   */
+  kill(): void {
+    if (this.proc) {
+      this.proc.kill('SIGKILL')
+      this.proc = null
+    }
+  }
+
+  private drain(): void {
+    const lines = this.buffer.split('\n')
+    this.buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+      try {
+        const msg = JSON.parse(trimmed) as InboundMessage
+        this.emit('message', msg)
+      } catch {
+        this.emit('log', `[non-json] ${trimmed}`)
+      }
+    }
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// HTTP transport (streamable-http)
+// ════════════════════════════════════════════════════════════
+
+export interface HttpTransportOptions {
+  url: string
+  headers?: Record<string, string>
+}
+
+/**
+ * Streamable-HTTP transport.
+ *
+ * Minimal implementation of the 2025-11-25 spec:
+ *   - Every outbound frame is POSTed with `Accept: application/json,
+ *     text/event-stream`.
+ *   - Request responses: a single `application/json` body OR a small SSE
+ *     stream that terminates after the response frame arrives.
+ *   - Notifications (no `id`): server returns 202 Accepted. We discard.
+ *
+ * Phase 1 scope: sufficient to talk to servers that follow the spec
+ * strictly (Brain MCP, most reference servers). Advanced features like
+ * GET-based server-push streams, session id headers, or OAuth redirect
+ * handshakes are intentionally out of scope — add when a real server
+ * requires them.
+ */
+export class HttpTransport extends EventEmitter implements MCPTransport {
+  readonly kind = 'http' as const
+  private stopped = false
+
+  constructor(private readonly opts: HttpTransportOptions) {
+    super()
+  }
+
+  async start(): Promise<void> {
+    // HTTP is stateless — nothing to open up-front. The first request
+    // forms the "connect" step from the protocol's point of view.
+  }
+
+  send(message: OutboundMessage): void {
+    if (this.stopped) {
+      throw new Error('HttpTransport: transport is stopped')
+    }
+
+    // Fire-and-forward; errors are surfaced via the `error` event so
+    // MCPConnection can reject the pending promise.
+    void this.post(message).catch((err) => {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)))
+    })
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true
+  }
+
+  private async post(message: OutboundMessage): Promise<void> {
+    const body = JSON.stringify(message)
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      ...(this.opts.headers ?? {}),
+    }
+
+    const res = await fetch(this.opts.url, { method: 'POST', headers, body })
+
+    // Notifications → server responds 202 Accepted with empty body.
+    if (res.status === 202) return
+
+    if (!res.ok) {
+      const text = await safeText(res)
+      throw new Error(`HTTP ${res.status} from MCP server: ${text.slice(0, 200)}`)
+    }
+
+    const ct = (res.headers.get('content-type') ?? '').toLowerCase()
+    if (ct.includes('application/json')) {
+      const json = (await res.json()) as InboundMessage
+      this.emit('message', json)
+      return
+    }
+
+    if (ct.includes('text/event-stream')) {
+      await this.consumeSse(res)
+      return
+    }
+
+    // Unknown content-type — try JSON parse, fall back to log.
+    const text = await safeText(res)
+    try {
+      this.emit('message', JSON.parse(text) as InboundMessage)
+    } catch {
+      this.emit('log', `[non-json] ${text.slice(0, 200)}`)
+    }
+  }
+
+  private async consumeSse(res: Response): Promise<void> {
+    if (!res.body) return
+    const reader = (res.body as ReadableStream<Uint8Array>).getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buffer += decoder.decode(value, { stream: true })
+        const { events, rest } = parseSseEvents(buffer)
+        buffer = rest
+        for (const evt of events) {
+          if (evt.data.length === 0) continue
+          try {
+            this.emit('message', JSON.parse(evt.data) as InboundMessage)
+          } catch {
+            this.emit('log', `[sse-non-json] ${evt.data.slice(0, 200)}`)
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock()
+    }
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// SSE transport (legacy)
+// ════════════════════════════════════════════════════════════
+
+export interface SseTransportOptions {
+  url: string
+  headers?: Record<string, string>
+}
+
+/**
+ * Legacy SSE transport.
+ *
+ * Opens a long-lived `GET <url>` stream to receive server→client frames
+ * and uses `POST <postEndpoint>` for client→server frames. The
+ * `postEndpoint` is discovered from the first `endpoint` SSE event, per
+ * the MCP legacy SSE convention.
+ *
+ * If the server never emits an endpoint event, POSTs fall back to the
+ * original URL with `?endpoint=messages` appended — some implementations
+ * accept that.
+ */
+export class SseTransport extends EventEmitter implements MCPTransport {
+  readonly kind = 'sse' as const
+  private abort: AbortController | null = null
+  private postEndpoint: string | null = null
+  private endpointReady?: Promise<void>
+  private endpointResolve?: () => void
+
+  constructor(private readonly opts: SseTransportOptions) {
+    super()
+  }
+
+  async start(): Promise<void> {
+    this.abort = new AbortController()
+    this.endpointReady = new Promise<void>((r) => {
+      this.endpointResolve = r
+    })
+
+    const headers: Record<string, string> = {
+      accept: 'text/event-stream',
+      ...(this.opts.headers ?? {}),
+    }
+
+    void fetch(this.opts.url, { headers, signal: this.abort.signal })
+      .then(async (res) => {
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status} opening SSE stream`)
+        }
+        await this.consume(res)
+      })
+      .catch((err) => {
+        if ((err as Error).name === 'AbortError') return
+        this.emit('error', err instanceof Error ? err : new Error(String(err)))
+        this.emit('exit', { code: null, signal: null })
+      })
+  }
+
+  send(message: OutboundMessage): void {
+    void this.postOnce(message).catch((err) => {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)))
+    })
+  }
+
+  async stop(): Promise<void> {
+    this.abort?.abort()
+    this.abort = null
+  }
+
+  private async postOnce(message: OutboundMessage): Promise<void> {
+    // Wait for the server to announce its POST endpoint (or timeout).
+    if (this.endpointReady) {
+      await Promise.race([
+        this.endpointReady,
+        new Promise<void>((r) => setTimeout(r, 2000)),
+      ])
+    }
+
+    const endpoint = this.postEndpoint ?? new URL('?endpoint=messages', this.opts.url).toString()
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      ...(this.opts.headers ?? {}),
+    }
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(message),
+    })
+    if (!res.ok && res.status !== 202) {
+      const text = await safeText(res)
+      throw new Error(`HTTP ${res.status} posting to SSE endpoint: ${text.slice(0, 200)}`)
+    }
+  }
+
+  private async consume(res: Response): Promise<void> {
+    if (!res.body) return
+    const reader = (res.body as ReadableStream<Uint8Array>).getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buffer += decoder.decode(value, { stream: true })
+        const { events, rest } = parseSseEvents(buffer)
+        buffer = rest
+        for (const evt of events) {
+          if (evt.event === 'endpoint') {
+            // Server announced its POST endpoint (absolute or relative).
+            const url = evt.data.trim()
+            this.postEndpoint = url.startsWith('http')
+              ? url
+              : new URL(url, this.opts.url).toString()
+            this.endpointResolve?.()
+            continue
+          }
+          if (evt.data.length === 0) continue
+          try {
+            this.emit('message', JSON.parse(evt.data) as InboundMessage)
+          } catch {
+            this.emit('log', `[sse-non-json] ${evt.data.slice(0, 200)}`)
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock()
+      this.emit('exit', { code: 0, signal: null })
+    }
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// Helpers
+// ════════════════════════════════════════════════════════════
+
+interface SseEvent {
+  event?: string
+  data: string
+}
+
+/**
+ * Parse SSE events from a buffer string. Returns emitted events and
+ * the unparsed tail (may be empty).
+ */
+function parseSseEvents(buffer: string): { events: SseEvent[]; rest: string } {
+  const events: SseEvent[] = []
+  const parts = buffer.split(/\r?\n\r?\n/)
+  const rest = parts.pop() ?? ''
+
+  for (const raw of parts) {
+    if (!raw.trim()) continue
+    const lines = raw.split(/\r?\n/)
+    let event: string | undefined
+    const dataLines: string[] = []
+    for (const line of lines) {
+      if (line.startsWith(':')) continue // SSE comment
+      const colon = line.indexOf(':')
+      const field = colon === -1 ? line : line.slice(0, colon)
+      const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+      if (field === 'event') event = value
+      else if (field === 'data') dataLines.push(value)
+    }
+    events.push({ event, data: dataLines.join('\n') })
+  }
+
+  return { events, rest }
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}

package/src/lib/types.ts

@@ -115,9 +115,17 @@ export interface ToolCallResult {
 // MCP Connection config
 // ════════════════════════════════════════════════════════════
 
-export interface MCPServerConfig {
-  /** Unique identifier for this connection */
-  id: string
+/**
+ * Transport kinds supported by MCPConnection.
+ * - stdio: local subprocess, newline-delimited JSON-RPC over stdin/stdout.
+ * - http : streamable-http (JSON-RPC POSTs returning text/event-stream or JSON).
+ * - sse  : legacy Server-Sent Events transport.
+ */
+export type MCPTransportKind = 'stdio' | 'http' | 'sse'
+
+/** stdio-specific config. */
+export interface MCPStdioConfig {
+  transport: 'stdio'
   /** Command to spawn the MCP server */
   command: string
   /** Command arguments */
@@ -126,11 +134,50 @@ export interface MCPServerConfig {
   cwd?: string
   /** Environment variables for the subprocess */
   env?: Record<string, string>
+}
+
+/** HTTP (streamable-http) specific config. */
+export interface MCPHttpConfig {
+  transport: 'http'
+  /** MCP endpoint URL */
+  url: string
+  /** Extra headers to attach to every POST */
+  headers?: Record<string, string>
+}
+
+/** Server-Sent Events (legacy) specific config. */
+export interface MCPSseConfig {
+  transport: 'sse'
+  /** MCP endpoint URL (SSE) */
+  url: string
+  /** Extra headers */
+  headers?: Record<string, string>
+}
+
+/**
+ * Transport discriminated union — exactly one variant per connection.
+ */
+export type MCPTransportConfig = MCPStdioConfig | MCPHttpConfig | MCPSseConfig
+
+export interface MCPServerConfig {
+  /** Unique identifier for this connection */
+  id: string
+  /** Transport — if omitted, falls back to stdio using command/args. */
+  transport?: MCPTransportConfig
+  /** Legacy stdio shorthand — command for the subprocess.
+   *  Ignored when `transport` is set. */
+  command?: string
+  /** Legacy stdio shorthand — args for the subprocess. */
+  args?: string[]
+  /** Working directory for the subprocess (stdio only) */
+  cwd?: string
+  /** Environment variables for the subprocess (stdio only) */
+  env?: Record<string, string>
   /** Role: 'memory' creates a MemoryProvider adapter, 'tools' exposes tools to agent */
   role?: 'memory' | 'tools' | 'both'
   /** Connection timeout in ms. Default: 10000 */
   timeoutMs?: number
-  /** Auto-restart on crash. Default: true */
+  /** Auto-restart on crash. Default: true (stdio only) */
   autoRestart?: boolean
 }