typeclaw 0.20.0 → 0.22.0

package/src/dreams/render.ts

@@ -0,0 +1,155 @@
+import { styleText } from 'node:util'
+
+import type { DreamCategory, DreamEntry, DreamEntryDetail } from './types'
+
+export type RenderOptions = { color: boolean }
+
+type ColorName = 'dim' | 'cyan' | 'green' | 'yellow' | 'magenta' | 'gray'
+
+function tint(opts: RenderOptions, color: ColorName, text: string): string {
+  if (!opts.color) return text
+  return styleText(color, text)
+}
+
+const CATEGORY_LABELS: Record<DreamCategory, string> = {
+  fragments: 'frag',
+  skills: 'skill',
+  'watermarks-only': 'watermarks',
+  snapshot: 'snapshot',
+  other: 'other',
+}
+
+export function renderListRow(entry: DreamEntry, opts: RenderOptions): string {
+  const emoji = entry.emoji ?? '·'
+  const sha = tint(opts, 'cyan', entry.shortSha)
+  const date = tint(opts, 'dim', formatShortDate(entry.committedAt))
+  const when = tint(opts, 'dim', `(${formatRelative(entry.committedAt)})`)
+  const summary = entry.summary ?? entry.subject
+  const badges = renderCategoryBadges(entry.categories, opts)
+  const head = `${emoji}  ${sha}  ${date} ${when}  ${summary}`
+  return badges.length > 0 ? `${head}  ${badges}` : head
+}
+
+function renderCategoryBadges(categories: DreamCategory[], opts: RenderOptions): string {
+  if (categories.length === 0) return ''
+  const meaningful = categories.filter((c) => c !== 'other')
+  const shown = meaningful.length > 0 ? meaningful : categories
+  const labels = shown.map((c) => CATEGORY_LABELS[c])
+  return tint(opts, 'magenta', labels.map((l) => `[${l}]`).join(' '))
+}
+
+export function renderDetail(entry: DreamEntry, opts: RenderOptions): string {
+  const lines: string[] = []
+  const emoji = entry.emoji ?? '·'
+  lines.push(`${emoji}  ${entry.subject}`)
+  lines.push(
+    tint(
+      opts,
+      'dim',
+      `${entry.shortSha} · ${formatTimestamp(entry.committedAt)} · ${formatRelative(entry.committedAt)}`,
+    ),
+  )
+
+  const detail = entry.detail
+  if (detail === undefined) {
+    lines.push('', tint(opts, 'dim', '(no detail loaded)'))
+    return lines.join('\n')
+  }
+
+  renderFragments(lines, detail, opts)
+  renderTopics(lines, detail, opts)
+  renderSkills(lines, detail, opts)
+
+  if (detail.stateChanged) lines.push('', tint(opts, 'dim', 'state: .dreaming-state.json advanced'))
+  for (const warning of detail.parseWarnings) lines.push(tint(opts, 'yellow', `⚠ ${warning}`))
+
+  if (isQuietDream(detail)) {
+    lines.push('', tint(opts, 'dim', 'No fragments promoted, no shards changed this run.'))
+  }
+  return lines.join('\n')
+}
+
+function renderFragments(lines: string[], detail: DreamEntryDetail, opts: RenderOptions): void {
+  if (detail.addedFragments.length === 0) return
+  lines.push('', section(opts, `fragments folded in (${detail.addedFragments.length})`))
+  for (const f of detail.addedFragments) {
+    const id = tint(opts, 'dim', `${f.streamDate ?? '????'}#${f.id}`)
+    const topic = f.topic !== null ? tint(opts, 'magenta', ` [${f.topic}]`) : ''
+    lines.push(`• ${id}${topic}`)
+    if (f.bodyPreview !== null) lines.push(`    ${tint(opts, 'gray', `"${f.bodyPreview}"`)}`)
+  }
+}
+
+function renderTopics(lines: string[], detail: DreamEntryDetail, opts: RenderOptions): void {
+  if (detail.changedTopics.length === 0) return
+  lines.push('', section(opts, `topic shards changed (${detail.changedTopics.length})`))
+  for (const t of detail.changedTopics) {
+    const counts =
+      t.additions !== null && t.deletions !== null ? tint(opts, 'dim', ` (+${t.additions} −${t.deletions})`) : ''
+    lines.push(`${statusGlyph(t.status, opts)} ${t.slug}${counts}`)
+  }
+}
+
+function renderSkills(lines: string[], detail: DreamEntryDetail, opts: RenderOptions): void {
+  if (detail.createdSkills.length === 0) return
+  lines.push('', section(opts, `skills distilled (${detail.createdSkills.length})`))
+  for (const s of detail.createdSkills)
+    lines.push(`${tint(opts, 'green', '✦')} ${s.name}  ${tint(opts, 'dim', s.path)}`)
+}
+
+export function toJsonShape(entry: DreamEntry): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    sha: entry.sha,
+    shortSha: entry.shortSha,
+    committedAt: entry.committedAt,
+    subject: entry.subject,
+    isDreamCommit: entry.isDreamCommit,
+    summary: entry.summary,
+    emoji: entry.emoji,
+    categories: entry.categories,
+  }
+  if (entry.detail !== undefined) base.detail = entry.detail
+  return base
+}
+
+function isQuietDream(detail: DreamEntryDetail): boolean {
+  return detail.addedFragments.length === 0 && detail.changedTopics.length === 0 && detail.createdSkills.length === 0
+}
+
+function section(opts: RenderOptions, label: string): string {
+  return tint(opts, 'dim', `── ${label} ──`)
+}
+
+function statusGlyph(status: string, opts: RenderOptions): string {
+  if (status === 'added') return tint(opts, 'green', '✚ added   ')
+  if (status === 'modified') return tint(opts, 'yellow', '✎ modified')
+  if (status === 'deleted') return tint(opts, 'dim', '✖ deleted ')
+  if (status === 'renamed') return tint(opts, 'cyan', '→ renamed ')
+  return '? unknown '
+}
+
+function formatRelative(iso: string): string {
+  const ms = Date.parse(iso)
+  if (Number.isNaN(ms)) return iso
+  const diff = Date.now() - ms
+  if (diff < 60_000) return 'just now'
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`
+  return `${Math.floor(diff / 86_400_000)}d ago`
+}
+
+function formatTimestamp(iso: string): string {
+  const ms = Date.parse(iso)
+  if (Number.isNaN(ms)) return iso
+  const d = new Date(ms)
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+function formatShortDate(iso: string): string {
+  const ms = Date.parse(iso)
+  if (Number.isNaN(ms)) return iso
+  const d = new Date(ms)
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}

package/src/dreams/types.ts

@@ -0,0 +1,50 @@
+// Mirrored from the bundled memory plugin's dreaming subagent rather than
+// imported: this host-stage viewer must stay decoupled from runtime plugin
+// internals, and only needs to RECOGNIZE the emoji set, not own it. The
+// grammar test asserts this list stays in sync with the runtime's pool.
+export const DREAM_EMOJI_POOL = ['💤', '🌙', '⭐', '🛌', '😴', '🧠', '💭', '🔮'] as const
+export type DreamEmoji = (typeof DREAM_EMOJI_POOL)[number]
+
+export type DreamCategory = 'fragments' | 'skills' | 'watermarks-only' | 'snapshot' | 'other'
+
+export type DreamEntry = {
+  sha: string
+  shortSha: string
+  subject: string
+  committedAt: string
+  isDreamCommit: boolean
+  summary: string | null
+  emoji: DreamEmoji | null
+  categories: DreamCategory[]
+  detail?: DreamEntryDetail
+}
+
+export type DreamEntryDetail = {
+  addedFragments: FragmentEventSummary[]
+  changedTopics: TopicShardChange[]
+  createdSkills: SkillCreation[]
+  stateChanged: boolean
+  parseWarnings: string[]
+}
+
+export type FragmentEventSummary = {
+  id: string
+  streamDate: string | null
+  topic: string | null
+  bodyPreview: string | null
+}
+
+export type ShardChangeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'unknown'
+
+export type TopicShardChange = {
+  path: string
+  slug: string
+  status: ShardChangeStatus
+  additions: number | null
+  deletions: number | null
+}
+
+export type SkillCreation = {
+  name: string
+  path: string
+}

package/src/mcp/catalog.ts

@@ -0,0 +1,29 @@
+export type McpCatalogServer = {
+  name: string
+  description?: string
+  connected: boolean
+  toolCount?: number
+}
+
+export function renderMcpCatalog(servers: McpCatalogServer[]): string {
+  const connected = servers.filter((server) => server.connected)
+  if (connected.length === 0) return ''
+
+  const lines = connected.map((server) => {
+    const toolCount = server.toolCount ?? 0
+    const description = server.description?.trim() ? server.description.trim() : 'no description'
+    return `- ${server.name} (${toolCount} tools): ${description}`
+  })
+
+  // WHY: this catalog is boot-stable for prompt-cache locality; MCP
+  // tools/list_changed notifications are intentionally not reflected here until
+  // the manager refresh path is invoked or the session restarts.
+  return [
+    '## MCP servers',
+    '',
+    'The following MCP servers are connected. Each exposes tools you can discover and call:',
+    ...lines,
+    '',
+    "Use `mcp_list_tools(server)` to see a server's tools, `mcp_describe(server, tool)` for a tool's input schema, and `mcp_call(server, tool, args)` to invoke it.",
+  ].join('\n')
+}

package/src/mcp/client.ts

@@ -0,0 +1,236 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { CallToolResultSchema, type CallToolResult, type ListToolsRequest } from '@modelcontextprotocol/sdk/types.js'
+
+import type { McpServer } from '@/config/config'
+import { resolveSecret } from '@/secrets/resolve'
+
+export type McpToolInfo = {
+  name: string
+  description: string
+  inputSchema: unknown
+}
+
+// The SDK defaults each request to 60s; typeclaw boot should fail fast enough
+// that one dead MCP server does not make the agent feel hung at startup.
+export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
+export const DEFAULT_MCP_CONNECT_TIMEOUT_MS = 15_000
+
+export type McpConnection = {
+  name: string
+  listTools(): Promise<McpToolInfo[]>
+  refresh(): Promise<McpToolInfo[]>
+  callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult>
+  close(): Promise<void>
+}
+
+export type McpSdkClient = {
+  listTools(
+    params?: ListToolsRequest['params'],
+    options?: RequestOptions,
+  ): Promise<{
+    tools: { name: string; description?: string; inputSchema: unknown }[]
+    nextCursor?: string
+  }>
+  callTool(
+    params: { name: string; arguments?: Record<string, unknown> },
+    resultSchema?: typeof CallToolResultSchema,
+    options?: RequestOptions,
+  ): Promise<CallToolResult>
+  close(): Promise<void>
+}
+
+type McpConnectClient = McpSdkClient & {
+  connect(transport: Transport, options?: RequestOptions): Promise<void>
+}
+
+export async function connectMcpServer(
+  server: McpServer,
+  opts: {
+    env: NodeJS.ProcessEnv
+    signal?: AbortSignal
+    connectTimeoutMs?: number
+    client?: McpConnectClient
+    transport?: Transport
+  },
+): Promise<McpConnection> {
+  const requestTimeout = server.timeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
+  const connectTimeout = opts.connectTimeoutMs ?? DEFAULT_MCP_CONNECT_TIMEOUT_MS
+  const client = opts.client ?? new Client({ name: 'typeclaw', version: '0.17.0' }, { capabilities: {} })
+  const transport = opts.transport ?? createTransport(server, opts.env)
+
+  try {
+    await withConnectDeadline(connectTimeout, opts.signal, (signal) =>
+      client.connect(transport, { signal, timeout: requestTimeout }),
+    )
+  } catch (cause) {
+    try {
+      await client.close()
+    } catch (closeCause) {
+      attachCloseCause(cause, closeCause)
+    }
+    throw cause
+  }
+
+  return createMcpConnection(
+    server.name,
+    {
+      listTools: (params, options) => client.listTools(params, options),
+      async callTool(params, _resultSchema, options) {
+        const result = await client.callTool(params, CallToolResultSchema, options)
+        return CallToolResultSchema.parse(result)
+      },
+      close: () => client.close(),
+    },
+    { timeoutMs: requestTimeout },
+  )
+}
+
+export function createMcpConnection(
+  name: string,
+  client: McpSdkClient,
+  opts: { timeoutMs?: number; signal?: AbortSignal } = {},
+): McpConnection {
+  let cachedTools: McpToolInfo[] | undefined
+  const timeout = opts.timeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
+
+  async function fetchTools(): Promise<McpToolInfo[]> {
+    const tools: McpToolInfo[] = []
+    let cursor: string | undefined
+    do {
+      const result = await client.listTools(cursor === undefined ? undefined : { cursor }, {
+        timeout,
+        signal: opts.signal,
+      })
+      tools.push(
+        ...result.tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description ?? '',
+          inputSchema: tool.inputSchema,
+        })),
+      )
+      cursor = result.nextCursor
+    } while (cursor !== undefined)
+
+    cachedTools = tools
+    return cachedTools
+  }
+
+  return {
+    name,
+    async listTools(): Promise<McpToolInfo[]> {
+      if (cachedTools !== undefined) return cachedTools
+      return fetchTools()
+    },
+    refresh(): Promise<McpToolInfo[]> {
+      cachedTools = undefined
+      return fetchTools()
+    },
+    callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult> {
+      return client.callTool({ name: toolName, arguments: args }, CallToolResultSchema, {
+        timeout,
+        signal: opts.signal,
+      })
+    },
+    close(): Promise<void> {
+      return client.close()
+    },
+  }
+}
+
+function createTransport(server: McpServer, env: NodeJS.ProcessEnv): Transport {
+  return server.command
+    ? new StdioClientTransport({ command: server.command, args: server.args, env: resolveServerEnv(server, env) })
+    : new StreamableHTTPClientTransport(new URL(requiredUrl(server)))
+}
+
+async function withConnectDeadline<T>(
+  timeoutMs: number,
+  parentSignal: AbortSignal | undefined,
+  fn: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const deadline = new AbortController()
+  const timer = setTimeout(() => deadline.abort(new Error('MCP connect timeout')), timeoutMs)
+  const merged = mergeSignals(parentSignal, deadline.signal)
+  const operation = fn(merged.signal)
+  let removeAbortListener = (): void => {}
+  const abort = new Promise<never>((_resolve, reject) => {
+    const onAbort = (): void => reject(merged.signal.reason)
+    removeAbortListener = (): void => merged.signal.removeEventListener('abort', onAbort)
+    if (merged.signal.aborted) onAbort()
+    else merged.signal.addEventListener('abort', onAbort, { once: true })
+  })
+  try {
+    return await Promise.race([operation, abort])
+  } finally {
+    clearTimeout(timer)
+    removeAbortListener()
+    if (merged.signal.aborted) void operation.catch(() => undefined)
+    merged.dispose()
+  }
+}
+
+function mergeSignals(...signals: (AbortSignal | undefined)[]): { signal: AbortSignal; dispose(): void } {
+  const activeSignals = signals.filter((signal): signal is AbortSignal => signal !== undefined)
+  if (activeSignals.length === 0) return { signal: new AbortController().signal, dispose() {} }
+  if (activeSignals.length === 1) return { signal: activeSignals[0]!, dispose() {} }
+
+  const controller = new AbortController()
+  const listeners: (() => void)[] = []
+  for (const signal of activeSignals) {
+    const abort = (): void => controller.abort(signal.reason)
+    if (signal.aborted) {
+      abort()
+      break
+    }
+    signal.addEventListener('abort', abort, { once: true })
+    listeners.push(() => signal.removeEventListener('abort', abort))
+  }
+
+  return {
+    signal: controller.signal,
+    dispose() {
+      for (const remove of listeners) remove()
+    },
+  }
+}
+
+function attachCloseCause(cause: unknown, closeCause: unknown): void {
+  if (!(cause instanceof Error)) return
+  const error = cause as Error & { cause?: unknown }
+  error.cause = { original: error.cause, close: closeCause }
+}
+
+// A stdio MCP server is a child process the agent spawns, so it must NOT
+// inherit the full parent environment: that env holds unrelated credentials
+// (FIREWORKS_API_KEY, GH_TOKEN, channel tokens) and inheriting them leaks every
+// secret to every server. We start from a minimal allowlist needed to spawn and
+// run a process (PATH/HOME to launch npx/bunx, locale + temp for correctness),
+// then overlay only the secrets the server explicitly declares. This mirrors
+// the bwrap sandbox's `--clearenv` + DEFAULT_SANDBOX_ENV leak guard.
+const BASE_ENV_ALLOWLIST = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ'] as const
+
+export function resolveServerEnv(server: Pick<McpServer, 'env'>, env: NodeJS.ProcessEnv): Record<string, string> {
+  const childEnv: Record<string, string> = {}
+  for (const key of BASE_ENV_ALLOWLIST) {
+    const value = env[key]
+    if (value !== undefined) childEnv[key] = value
+  }
+
+  for (const [key, secret] of Object.entries(server.env)) {
+    const explicitKeyValue = env[key]
+    const resolved =
+      explicitKeyValue !== undefined && explicitKeyValue !== '' ? explicitKeyValue : resolveSecret(secret, key, env)
+    if (resolved !== undefined) childEnv[key] = resolved
+  }
+
+  return childEnv
+}
+
+function requiredUrl(server: McpServer): string {
+  if (server.url !== undefined) return server.url
+  throw new Error(`MCP server "${server.name}" is missing url`)
+}

package/src/mcp/index.ts

@@ -0,0 +1,25 @@
+export {
+  connectMcpServer,
+  createMcpConnection,
+  resolveServerEnv,
+  type McpConnection,
+  type McpSdkClient,
+  type McpToolInfo,
+} from './client'
+export {
+  createMcpManager,
+  namespaceToolName,
+  parseNamespacedTool,
+  type ConnectMcpServerFn,
+  type McpConnectResult,
+  type McpManager,
+} from './manager'
+export { renderMcpCatalog, type McpCatalogServer } from './catalog'
+export {
+  createMcpDispatcherTools,
+  MCP_DISPATCHER_TOOL_NAMES,
+  type McpCallArgs,
+  type McpDescribeArgs,
+  type McpDispatcherTool,
+  type McpListToolsArgs,
+} from './tools'

package/src/mcp/manager.ts

@@ -0,0 +1,156 @@
+import type { McpServer } from '@/config/config'
+
+import { connectMcpServer, type McpConnection } from './client'
+
+const TOOL_NAMESPACE_SEPARATOR = '__'
+
+export type McpConnectResult =
+  | { ok: true; name: string; connection: McpConnection; toolCount: number }
+  | { ok: false; name: string; error: Error }
+
+export type McpRefreshResult = { ok: true; name: string; toolCount: number } | { ok: false; name: string; error: Error }
+
+export type McpManager = {
+  connectAll(opts?: { signal?: AbortSignal }): Promise<McpConnectResult[]>
+  getConnection(name: string): McpConnection | undefined
+  listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[]
+  refresh(): Promise<McpRefreshResult[]>
+  closeAll(): Promise<void>
+}
+
+export type ConnectMcpServerFn = (
+  server: McpServer,
+  opts: { env: NodeJS.ProcessEnv; signal?: AbortSignal },
+) => Promise<McpConnection>
+
+export function createMcpManager(
+  servers: McpServer[],
+  opts: { env: NodeJS.ProcessEnv; connect?: ConnectMcpServerFn },
+): McpManager {
+  const activeServers = servers.filter((server) => server.enabled)
+  const connect = opts.connect ?? connectMcpServer
+  const connections = new Map<string, McpConnection>()
+  const toolCounts = new Map<string, number>()
+
+  return {
+    async connectAll(connectOpts: { signal?: AbortSignal } = {}): Promise<McpConnectResult[]> {
+      const firstIndexByName = new Map<string, number>()
+      const results = await Promise.all(
+        activeServers.map((server, index): Promise<McpConnectResult> => {
+          // The name is the tool namespace and the connections key, so a second
+          // server sharing a name would silently shadow the first. Fail the
+          // duplicate fast instead of connecting it, keeping routing unambiguous.
+          const firstIndex = firstIndexByName.get(server.name)
+          if (firstIndex !== undefined) {
+            return Promise.resolve({
+              ok: false,
+              name: server.name,
+              error: new Error(
+                `mcpServers[${index}].name duplicates mcpServers[${firstIndex}].name ('${server.name}')`,
+              ),
+            })
+          }
+          firstIndexByName.set(server.name, index)
+          return connectOne(server, opts.env, connect, connectOpts.signal)
+        }),
+      )
+      for (const result of results) {
+        if (!result.ok) continue
+        connections.set(result.name, result.connection)
+        toolCounts.set(result.name, result.toolCount)
+      }
+      return results
+    },
+    getConnection(name: string): McpConnection | undefined {
+      return connections.get(name)
+    },
+    listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[] {
+      return activeServers.map((server) => {
+        const toolCount = toolCounts.get(server.name)
+        return {
+          name: server.name,
+          connected: connections.has(server.name),
+          ...(server.description === undefined ? {} : { description: server.description }),
+          ...(toolCount === undefined ? {} : { toolCount }),
+        }
+      })
+    },
+    async refresh(): Promise<McpRefreshResult[]> {
+      // One unhealthy connection must not discard healthy servers' tool-count
+      // updates, so each refresh is isolated and reported per-server instead of
+      // letting a single rejection fail the whole batch.
+      return Promise.all(
+        [...connections.entries()].map(async ([name, connection]): Promise<McpRefreshResult> => {
+          try {
+            const tools = await connection.refresh()
+            toolCounts.set(name, tools.length)
+            return { ok: true, name, toolCount: tools.length }
+          } catch (cause) {
+            return { ok: false, name, error: normalizeError(cause) }
+          }
+        }),
+      )
+    },
+    async closeAll(): Promise<void> {
+      await Promise.allSettled([...connections.values()].map((connection) => connection.close()))
+      connections.clear()
+      toolCounts.clear()
+    },
+  }
+}
+
+export function namespaceToolName(server: string, tool: string): string {
+  return `${server}${TOOL_NAMESPACE_SEPARATOR}${tool}`
+}
+
+export function parseNamespacedTool(namespaced: string): { server: string; tool: string } | undefined {
+  // Config validation reserves `__` out of server names; splitting on the first
+  // separator is therefore unambiguous even when MCP tool names contain it.
+  const separatorIndex = namespaced.indexOf(TOOL_NAMESPACE_SEPARATOR)
+  if (separatorIndex <= 0) return undefined
+
+  const toolStart = separatorIndex + TOOL_NAMESPACE_SEPARATOR.length
+  if (toolStart >= namespaced.length) return undefined
+
+  return { server: namespaced.slice(0, separatorIndex), tool: namespaced.slice(toolStart) }
+}
+
+async function connectOne(
+  server: McpServer,
+  env: NodeJS.ProcessEnv,
+  connect: ConnectMcpServerFn,
+  signal: AbortSignal | undefined,
+): Promise<McpConnectResult> {
+  let connection: McpConnection | undefined
+  try {
+    connection = await connect(server, { env, signal })
+    const tools = await connection.listTools()
+    return { ok: true, name: server.name, connection, toolCount: tools.length }
+  } catch (cause) {
+    const closeError = connection === undefined ? undefined : await closeAfterFailedCatalog(connection)
+    if (closeError !== undefined) {
+      return {
+        ok: false,
+        name: server.name,
+        error: new Error(`MCP server "${server.name}" failed to connect and then failed to close`, {
+          cause: { original: cause, close: closeError },
+        }),
+      }
+    }
+    return { ok: false, name: server.name, error: normalizeError(cause) }
+  }
+}
+
+async function closeAfterFailedCatalog(connection: McpConnection): Promise<Error | undefined> {
+  try {
+    await connection.close()
+    return undefined
+  } catch (cause) {
+    return normalizeError(cause)
+  }
+}
+
+function normalizeError(cause: unknown): Error {
+  if (cause instanceof Error) return cause
+  return new Error(String(cause))
+}