@auggieteo/dsh-mcp-adapter 0.1.0

package/src/host/manager.js

@@ -0,0 +1,516 @@
+import {
+  REQUEST_TIMEOUT_MS,
+  createMcpConnection,
+} from './mcp-connection.js'
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function abortError(signal) {
+  if (signal.reason instanceof Error) return signal.reason
+  const error = new Error('Operation aborted')
+  error.name = 'AbortError'
+  return error
+}
+
+function waitWithSignal(promise, signal) {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.reject(abortError(signal))
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal))
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort)
+    })
+  })
+}
+
+function cloneJson(value) {
+  return structuredClone(value)
+}
+
+function equalJson(left, right) {
+  if (left === right) return true
+  if (typeof left !== typeof right || left === null || right === null) return false
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+      return false
+    }
+    return left.every((item, index) => equalJson(item, right[index]))
+  }
+  if (typeof left !== 'object') return false
+  const leftKeys = Object.keys(left).sort()
+  const rightKeys = Object.keys(right).sort()
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) => key === rightKeys[index] && equalJson(left[key], right[key]),
+    )
+  )
+}
+
+function normalizeTool(tool) {
+  return cloneJson({
+    name: tool.name,
+    ...(tool.description === undefined ? {} : { description: tool.description }),
+    inputSchema: tool.inputSchema,
+    ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+    ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+  })
+}
+
+function connectionConfig(config) {
+  return {
+    command: config.command,
+    args: config.args,
+    env: config.env,
+    url: config.url,
+    headers: config.headers,
+    disabled: config.disabled,
+    lifecycle: config.lifecycle,
+  }
+}
+
+function initialState(config) {
+  return config.disabled ? 'disabled' : 'disconnected'
+}
+
+function createRecord(name, config) {
+  return {
+    name,
+    config,
+    state: initialState(config),
+    message: undefined,
+    transportType: undefined,
+    tools: [],
+    connection: undefined,
+    connectPromise: undefined,
+    connectAbort: undefined,
+    generation: 0,
+    activeCalls: 0,
+    cancelIdle: undefined,
+    lastUsedAt: undefined,
+  }
+}
+
+/**
+ * Host owner for MCP connections and cached tool metadata.
+ *
+ * The manager does not expose SDK Client or Transport instances. Consumers get
+ * detached JSON snapshots and call through manager methods, so live Host data
+ * never crosses the client RPC boundary by accident.
+ */
+export class McpClientManager {
+  constructor(
+    settingsScope,
+    {
+      connectionFactory = createMcpConnection,
+      schedule,
+      now = Date.now,
+    } = {},
+  ) {
+    if (typeof schedule !== 'function') {
+      throw new TypeError('McpClientManager requires a lifecycle-owned schedule(callback, delay)')
+    }
+
+    this.settingsScope = settingsScope
+    this.connectionFactory = connectionFactory
+    this.schedule = schedule
+    this.now = now
+    this.records = new Map()
+    this.listeners = new Set()
+    this.disposed = false
+
+    this.installConfig(settingsScope.get())
+    this.unwatch = settingsScope.watch((next) => this.reconcile(next))
+  }
+
+  installConfig(settings) {
+    for (const [name, config] of Object.entries(settings.mcpServers)) {
+      this.records.set(name, createRecord(name, config))
+    }
+  }
+
+  async reconcile(settings) {
+    if (this.disposed) return
+    const nextServers = settings.mcpServers
+
+    for (const [name, record] of [...this.records]) {
+      const next = nextServers[name]
+      if (next === undefined) {
+        await this.closeRecord(record, 'removed')
+        this.records.delete(name)
+        continue
+      }
+      if (!equalJson(record.config, next)) {
+        const mustReconnect = !equalJson(
+          connectionConfig(record.config),
+          connectionConfig(next),
+        )
+        const idleTimeoutChanged =
+          record.config.idleTimeoutMinutes !== next.idleTimeoutMinutes
+        if (mustReconnect) {
+          await this.closeRecord(record, 'changed')
+          record.state = initialState(next)
+          record.message = undefined
+          record.transportType = undefined
+          record.tools = []
+        }
+        record.config = next
+        if (!mustReconnect && idleTimeoutChanged) this.scheduleIdle(record)
+      }
+    }
+
+    for (const [name, config] of Object.entries(nextServers)) {
+      if (!this.records.has(name)) this.records.set(name, createRecord(name, config))
+    }
+
+    this.emit()
+  }
+
+  subscribe(listener) {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  emit() {
+    const snapshot = this.statusSnapshot()
+    for (const listener of this.listeners) {
+      try {
+        listener(snapshot)
+      } catch {
+        // Status observers cannot break connection ownership.
+      }
+    }
+  }
+
+  requireRecord(name) {
+    const record = this.records.get(name)
+    if (record === undefined) throw new Error(`Unknown MCP server ${JSON.stringify(name)}`)
+    if (record.config.disabled) throw new Error(`MCP server ${JSON.stringify(name)} is disabled`)
+    return record
+  }
+
+  getServerConfig(name) {
+    const record = this.records.get(name)
+    return record === undefined ? undefined : cloneJson(record.config)
+  }
+
+  getCachedTools(name) {
+    const record = this.records.get(name)
+    return record === undefined ? [] : cloneJson(record.tools)
+  }
+
+  statusSnapshot() {
+    return {
+      servers: [...this.records.values()].map((record) => ({
+        name: record.name,
+        state: record.state,
+        ...(record.message === undefined ? {} : { message: record.message }),
+        ...(record.transportType === undefined
+          ? {}
+          : { transport: record.transportType }),
+        toolCount: record.tools.length,
+        ...(record.lastUsedAt === undefined
+          ? {}
+          : { lastUsedAt: record.lastUsedAt }),
+      })),
+    }
+  }
+
+  catalogSnapshot() {
+    return {
+      servers: [...this.records.values()].map((record) => ({
+        name: record.name,
+        disabled: record.config.disabled,
+        state: record.state,
+        tools: cloneJson(record.tools),
+      })),
+    }
+  }
+
+  setState(record, state, message) {
+    record.state = state
+    record.message = message
+    this.emit()
+  }
+
+  cancelIdle(record) {
+    record.cancelIdle?.()
+    record.cancelIdle = undefined
+  }
+
+  scheduleIdle(record) {
+    this.cancelIdle(record)
+    if (
+      this.disposed ||
+      record.connection === undefined ||
+      record.activeCalls > 0
+    ) {
+      return
+    }
+
+    const delay = record.config.idleTimeoutMinutes * 60_000
+    record.cancelIdle = this.schedule(async () => {
+      record.cancelIdle = undefined
+      if (record.activeCalls > 0) {
+        this.scheduleIdle(record)
+        return
+      }
+      await this.disconnect(record.name, 'idle timeout')
+    }, delay)
+  }
+
+  touch(record) {
+    record.lastUsedAt = this.now()
+    this.scheduleIdle(record)
+  }
+
+  callbacksFor(record, generation) {
+    return {
+      onToolsChanged: (error, tools) => {
+        if (record.generation !== generation || this.disposed) return
+        if (error !== null) {
+          this.setState(record, 'error', `Tool list refresh failed: ${errorMessage(error)}`)
+          return
+        }
+        if (tools !== null) {
+          record.tools = tools.map(normalizeTool)
+          record.message = undefined
+          if (record.connection !== undefined) record.state = 'connected'
+          this.emit()
+        }
+      },
+      onError: (error) => {
+        if (record.generation !== generation || this.disposed) return
+        this.setState(record, 'error', errorMessage(error))
+      },
+      onClose: () => {
+        if (record.generation !== generation || this.disposed) return
+        record.connection = undefined
+        record.transportType = undefined
+        this.cancelIdle(record)
+        this.setState(record, 'disconnected', 'Connection closed')
+      },
+    }
+  }
+
+  async ensureConnection(record, signal) {
+    if (record.connection !== undefined) return record.connection
+    if (record.connectPromise !== undefined) {
+      return waitWithSignal(record.connectPromise, signal)
+    }
+
+    const generation = ++record.generation
+    const controller = new AbortController()
+    record.connectAbort = controller
+    this.setState(record, 'connecting')
+
+    const promise = (async () => {
+      let connection
+      try {
+        connection = await this.connectionFactory(
+          record.name,
+          record.config,
+          this.callbacksFor(record, generation),
+          controller.signal,
+        )
+
+        if (
+          this.disposed ||
+          record.generation !== generation ||
+          record.config.disabled
+        ) {
+          throw new Error(`MCP server ${JSON.stringify(record.name)} changed while connecting`)
+        }
+
+        record.connection = connection
+        record.transportType = connection.transportType
+        record.state = 'connected'
+        record.message = undefined
+
+        const listed = await connection.client.listTools(undefined, {
+          signal: controller.signal,
+          timeout: REQUEST_TIMEOUT_MS,
+        })
+        record.tools = listed.tools.map(normalizeTool)
+        this.touch(record)
+        this.emit()
+        return connection
+      } catch (error) {
+        if (connection !== undefined) await connection.close()
+        if (record.generation === generation && !this.disposed) {
+          record.connection = undefined
+          record.transportType = undefined
+          this.setState(record, 'error', errorMessage(error))
+        }
+        throw error
+      } finally {
+        if (record.generation === generation) record.connectAbort = undefined
+      }
+    })()
+
+    record.connectPromise = promise
+    const clearPromise = () => {
+      if (record.connectPromise === promise) record.connectPromise = undefined
+    }
+    promise.then(clearPromise, clearPromise)
+    return waitWithSignal(promise, signal)
+  }
+
+  async withConnection(name, signal, operation) {
+    if (signal?.aborted) throw abortError(signal)
+    const record = this.requireRecord(name)
+    record.activeCalls += 1
+    this.cancelIdle(record)
+    try {
+      const connection = await this.ensureConnection(record, signal)
+      return await operation(connection, record)
+    } finally {
+      record.activeCalls -= 1
+      this.touch(record)
+    }
+  }
+
+  async listTools(name, { refresh = false, signal } = {}) {
+    return this.withConnection(name, signal, async (connection, record) => {
+      if (refresh) {
+        const listed = await connection.client.listTools(undefined, {
+          signal,
+          timeout: REQUEST_TIMEOUT_MS,
+        })
+        record.tools = listed.tools.map(normalizeTool)
+        this.emit()
+      }
+      return cloneJson(record.tools)
+    })
+  }
+
+  async callTool(name, toolName, args = {}, { signal } = {}) {
+    return this.withConnection(name, signal, async (connection) => {
+      return connection.client.callTool(
+        { name: toolName, arguments: args },
+        undefined,
+        { signal, timeout: REQUEST_TIMEOUT_MS },
+      )
+    })
+  }
+
+  async disconnect(name, reason = 'disconnected') {
+    const record = this.records.get(name)
+    if (record === undefined) return false
+    await this.closeRecord(record, reason)
+    if (record.config.disabled) {
+      this.setState(record, 'disabled')
+    } else {
+      this.setState(record, 'disconnected')
+    }
+    return true
+  }
+
+  async closeRecord(record) {
+    record.generation += 1
+    this.cancelIdle(record)
+    record.connectAbort?.abort()
+    record.connectAbort = undefined
+    const connection = record.connection
+    const connecting = record.connectPromise
+    record.connection = undefined
+    record.connectPromise = undefined
+    record.transportType = undefined
+    if (connection !== undefined) await connection.close()
+    if (connecting !== undefined) await connecting.catch(() => undefined)
+  }
+
+  async dispose() {
+    if (this.disposed) return
+    this.disposed = true
+    this.unwatch?.()
+    await Promise.all([...this.records.values()].map((record) => this.closeRecord(record)))
+    this.listeners.clear()
+  }
+}
+
+export const MCP_RPC_CHANNEL = '/mcp-adapter'
+
+export function installMcpManagerRpc(ctx, manager) {
+  ctx.connection.rpc.handle(
+    MCP_RPC_CHANNEL,
+    async (endpoint, payload, signal) => {
+      if (endpoint === 'status') {
+        return { ok: true, value: manager.statusSnapshot() }
+      }
+      if (endpoint === 'catalog') {
+        return { ok: true, value: manager.catalogSnapshot() }
+      }
+      if (endpoint === 'overview') {
+        return {
+          ok: true,
+          value: {
+            status: manager.statusSnapshot(),
+            catalog: manager.catalogSnapshot(),
+          },
+        }
+      }
+      if (endpoint === 'reconnect') {
+        if (
+          typeof payload !== 'object' ||
+          payload === null ||
+          Array.isArray(payload) ||
+          typeof payload.server !== 'string' ||
+          payload.server.trim() === ''
+        ) {
+          return {
+            ok: false,
+            error: {
+              code: 'bad-request',
+              message: 'Reconnect requires a non-empty Server name.',
+              details: { issues: [] },
+            },
+          }
+        }
+        const serverName = payload.server.trim()
+        try {
+          await manager.disconnect(serverName, 'manual reconnect')
+          await manager.listTools(serverName, { signal })
+          return {
+            ok: true,
+            value: {
+              status: manager.statusSnapshot(),
+              catalog: manager.catalogSnapshot(),
+            },
+          }
+        } catch (error) {
+          return {
+            ok: false,
+            error: {
+              code: 'mcp-reconnect-failed',
+              message: errorMessage(error),
+              details: { issues: [] },
+            },
+          }
+        }
+      }
+      return {
+        ok: false,
+        error: {
+          code: 'bad-request',
+          message: `Unknown MCP Adapter endpoint ${JSON.stringify(endpoint)}`,
+          details: { issues: [] },
+        },
+      }
+    },
+    { authority: 'trusted-host' },
+  )
+}
+
+export function installMcpManager(ctx, settingsScope, options = {}) {
+  const manager = new McpClientManager(settingsScope, {
+    schedule: (callback, delay) => ctx.timeout(callback, delay),
+    ...options,
+  })
+  ctx.provide('mcpManager', manager)
+  ctx.effect(() => () => manager.dispose(), 'dsh-mcp-adapter: manager lifecycle')
+  return manager
+}

package/src/host/mcp-connection.js

@@ -0,0 +1,157 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
+import {
+  StdioClientTransport,
+  getDefaultEnvironment,
+} from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+export const CONNECT_TIMEOUT_MS = 30_000
+export const REQUEST_TIMEOUT_MS = 30_000
+
+const DEFAULT_SDK = {
+  Client,
+  SSEClientTransport,
+  StdioClientTransport,
+  StreamableHTTPClientTransport,
+  getDefaultEnvironment,
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function createClient(serverName, callbacks, sdk) {
+  const client = new sdk.Client(
+    { name: 'dsh-mcp-adapter', version: '0.1.0' },
+    {
+      listChanged: {
+        tools: {
+          autoRefresh: true,
+          debounceMs: 100,
+          onChanged(error, tools) {
+            callbacks.onToolsChanged?.(error, tools)
+          },
+        },
+      },
+    },
+  )
+
+  client.onerror = (error) => callbacks.onError?.(error)
+  client.onclose = () => callbacks.onClose?.()
+  return client
+}
+
+async function closeQuietly(client, transport) {
+  try {
+    await client?.close()
+  } catch {
+    try {
+      await transport?.close()
+    } catch {
+      // The failed connection has no remaining lifecycle work.
+    }
+  }
+}
+
+async function connectClient(client, transport, signal) {
+  await client.connect(transport, {
+    signal,
+    timeout: CONNECT_TIMEOUT_MS,
+  })
+}
+
+/**
+ * Create one connected SDK client. HTTP follows the MCP compatibility rule:
+ * attempt streamable HTTP first, then retry once with the legacy SSE transport
+ * and a fresh Client/Transport pair.
+ *
+ * `sdk` is injectable for transport-contract tests. Production callers omit it.
+ */
+export async function createMcpConnection(
+  serverName,
+  config,
+  callbacks = {},
+  signal,
+  sdk = DEFAULT_SDK,
+) {
+  if (typeof config.command === 'string') {
+    const client = createClient(serverName, callbacks, sdk)
+    const transport = new sdk.StdioClientTransport({
+      command: config.command,
+      args: config.args,
+      env: {
+        ...sdk.getDefaultEnvironment(),
+        ...config.env,
+      },
+      stderr: 'pipe',
+    })
+
+    let stderr = ''
+    transport.stderr?.on?.('data', (chunk) => {
+      stderr = `${stderr}${String(chunk)}`.slice(-8192)
+    })
+
+    try {
+      await connectClient(client, transport, signal)
+      return {
+        client,
+        transport,
+        transportType: 'stdio',
+        diagnostic: () => stderr.trim(),
+        close: () => closeQuietly(client, transport),
+      }
+    } catch (error) {
+      await closeQuietly(client, transport)
+      const detail = stderr.trim()
+      if (detail === '') throw error
+      throw new Error(`${errorMessage(error)}\nServer stderr:\n${detail}`, {
+        cause: error,
+      })
+    }
+  }
+
+  const url = new URL(config.url)
+  const requestInit = { headers: { ...config.headers } }
+
+  let streamableClient = createClient(serverName, callbacks, sdk)
+  let streamableTransport = new sdk.StreamableHTTPClientTransport(url, {
+    requestInit,
+  })
+  let streamableError
+
+  try {
+    await connectClient(streamableClient, streamableTransport, signal)
+    return {
+      client: streamableClient,
+      transport: streamableTransport,
+      transportType: 'streamable-http',
+      diagnostic: () => '',
+      close: () => closeQuietly(streamableClient, streamableTransport),
+    }
+  } catch (error) {
+    streamableError = error
+    await closeQuietly(streamableClient, streamableTransport)
+  }
+
+  const sseClient = createClient(serverName, callbacks, sdk)
+  const sseTransport = new sdk.SSEClientTransport(url, { requestInit })
+  try {
+    await connectClient(sseClient, sseTransport, signal)
+    return {
+      client: sseClient,
+      transport: sseTransport,
+      transportType: 'sse',
+      diagnostic: () => '',
+      close: () => closeQuietly(sseClient, sseTransport),
+    }
+  } catch (sseError) {
+    await closeQuietly(sseClient, sseTransport)
+    throw new Error(
+      `Could not connect to ${serverName} with streamable HTTP or SSE. ` +
+        `Streamable HTTP: ${errorMessage(streamableError)}. ` +
+        `SSE: ${errorMessage(sseError)}.`,
+      { cause: sseError },
+    )
+  }
+}