typeclaw 0.21.0 → 0.23.0

package/src/config/config.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 import { channelsSchema } from '@/channels/schema'
 import { commitSystemFileSync } from '@/git/system-commit'
 import { rolesConfigSchema } from '@/permissions/schema'
+import { secretFieldSchema } from '@/secrets/resolve'
 
 import {
   DEFAULT_MODEL_REF,
@@ -30,6 +31,30 @@ const DEFAULT_PORT = 8973
 // of files like `mounts/.git` or `mounts/Hello`.
 const MOUNT_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/
 
+// Shell-portable env var identifier: a leading letter or underscore followed by
+// letters, digits, or underscores. MCP `env` keys are passed verbatim to a child
+// process environment, so an invalid identifier (spaces, `=`, leading digit)
+// would be silently dropped or corrupt the spawned server's env.
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// Upper bound for a per-server MCP request timeout: 10 minutes. Long-running
+// MCP tools (large crawls, builds) can legitimately take minutes, but a ceiling
+// guards against fat-finger values that would re-introduce the unbounded-hang
+// failure mode the explicit timeouts exist to prevent.
+const MCP_MAX_TIMEOUT_MS = 600_000
+
+// URL schemes are case-insensitive (RFC 3986), and the WHATWG parser normalizes
+// `.protocol` to lowercase. Checking the parsed protocol instead of a raw
+// `startsWith` keeps `HTTPS://…` valid, which `z.string().url()` already accepts.
+function isHttpProtocol(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol
+    return protocol === 'http:' || protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
 export const mountSchema = z.object({
   name: z.string().regex(MOUNT_NAME_PATTERN, 'mount name must be lowercase alphanumeric with - or _'),
   path: z.string().min(1),
@@ -39,6 +64,66 @@ export const mountSchema = z.object({
 
 export type Mount = z.infer<typeof mountSchema>
 
+// MCP servers are keyed by the same shell/disk-safe namespace as mounts because
+// the name becomes the tool namespace exposed to the agent. The transport is an
+// XOR on purpose: stdio servers are child processes (`command` + `args` + env),
+// while Streamable HTTP servers are remote endpoints (`url`); accepting both
+// would make ownership, lifetime, and credential injection ambiguous at boot.
+export const mcpServerSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(MOUNT_NAME_PATTERN, 'MCP server name must be lowercase alphanumeric with - or _')
+      .refine((name) => !name.includes('__'), {
+        message: "MCP server name must not contain '__' (reserved as the tool-namespace separator)",
+      }),
+    description: z.string().optional(),
+    // Default true so omitting the field keeps the server on; set false to keep config but skip connecting.
+    enabled: z.boolean().default(true),
+    timeoutMs: z.number().int().positive().max(MCP_MAX_TIMEOUT_MS).optional(),
+    command: z.string().trim().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    url: z
+      .string()
+      .url()
+      .refine((u) => isHttpProtocol(u), {
+        message: 'MCP server url must use http:// or https://',
+      })
+      .optional(),
+    env: z
+      .record(z.string().regex(ENV_NAME_PATTERN, 'env var name must be a valid identifier'), secretFieldSchema)
+      .default({}),
+  })
+  .refine((server) => (server.command !== undefined) !== (server.url !== undefined), {
+    message: 'MCP server must be either stdio (command) or http (url), not both or neither',
+  })
+
+export type McpServer = z.infer<typeof mcpServerSchema>
+
+// The name becomes the `<server>__<tool>` namespace at dispatch, so duplicates
+// would make tool lookup ambiguous and silently shadow one server behind
+// another. Reject them with an indexed path so the error points at the
+// offending entry instead of the whole array.
+const mcpServersArraySchema = z
+  .array(mcpServerSchema)
+  .default([])
+  .superRefine((entries, ctx) => {
+    const seen = new Map<string, number>()
+    for (let i = 0; i < entries.length; i++) {
+      const name = entries[i]!.name
+      const prev = seen.get(name)
+      if (prev !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [i, 'name'],
+          message: `mcpServers[${i}].name duplicates mcpServers[${prev}].name ('${name}')`,
+        })
+      } else {
+        seen.set(name, i)
+      }
+    }
+  })
+
 const portNumber = z.number().int().min(1).max(65535)
 
 // `allow` is the discriminator between "forward everything" ('*') and a fixed
@@ -391,6 +476,7 @@ export const configSchema = z
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
     mounts: z.array(mountSchema).default([]),
+    mcpServers: mcpServersArraySchema,
     plugins: z.array(z.string().min(1)).default([]),
     // Additional names the agent answers to in channel engagement, on top
     // of `basename(agentDir)` which is always implicit. Each entry is a
@@ -538,6 +624,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   models: 'applied',
   port: 'restart-required',
   mounts: 'restart-required',
+  mcpServers: 'restart-required',
   plugins: 'restart-required',
   alias: 'applied',
   channels: 'applied',
@@ -638,6 +725,8 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     'git',
     'roles',
     'permissions',
+    'tunnels',
+    'mcpServers',
   ])
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {

package/src/inspect/index.ts

@@ -30,10 +30,9 @@ export type RunInspectOptions = {
   stdout: (line: string) => void
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
+  // Aborting this signal stops the live tail and returns escToPicker=true; the
+  // caller's loop inspects its own scope intent to tell back from exit.
   signal?: AbortSignal
-  // Aborting escSignal (and only escSignal) returns escToPicker=true so a
-  // caller-side loop can re-open the picker; signal still means process exit.
-  escSignal?: AbortSignal
   liveHint?: string
 }
 
@@ -81,7 +80,6 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
     stderr: opts.stderr,
     ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
     ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
-    ...(opts.escSignal !== undefined ? { escSignal: opts.escSignal } : {}),
     ...(opts.liveHint !== undefined ? { liveHint: opts.liveHint } : {}),
   })
   if (streamResult.escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
@@ -147,7 +145,6 @@ async function streamSession(opts: {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
-  escSignal?: AbortSignal
   liveHint?: string
 }): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
@@ -161,26 +158,25 @@ async function streamSession(opts: {
     }
   }
 
-  const escAborted = (): boolean => opts.escSignal?.aborted === true
+  const aborted = (): boolean => opts.signal?.aborted === true
 
   for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
-    if (escAborted()) return { escToPicker: true }
+    if (aborted()) return { escToPicker: true }
     emit(event)
   }
 
   if (opts.liveSource === undefined) {
     if (!opts.json) opts.stdout('─── end of transcript ───')
-    return { escToPicker: escAborted() }
+    return { escToPicker: aborted() }
   }
 
-  if (escAborted()) return { escToPicker: true }
+  if (aborted()) return { escToPicker: true }
 
-  const combinedSignal = combineSignals(opts.signal, opts.escSignal)
   let sessionLive = false
   const liveIter = opts.liveSource({
     sessionId: opts.summary.sessionId,
     ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
-    ...(combinedSignal !== undefined ? { signal: combinedSignal } : {}),
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     onSubscribed: (live) => {
       sessionLive = live
     },
@@ -204,21 +200,7 @@ async function streamSession(opts: {
     opts.stderr(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
   }
   if (!opts.json) opts.stdout('─── end of transcript ───')
-  return { escToPicker: escAborted() && opts.signal?.aborted !== true }
-}
-
-function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
-  if (a === undefined) return b
-  if (b === undefined) return a
-  if (a.aborted) return a
-  if (b.aborted) return b
-  const ctrl = new AbortController()
-  const onAbort = (): void => {
-    ctrl.abort()
-  }
-  a.addEventListener('abort', onAbort, { once: true })
-  b.addEventListener('abort', onAbort, { once: true })
-  return ctrl.signal
+  return { escToPicker: aborted() }
 }
 
 function divider(color: boolean, text: string): string {

package/src/inspect/live.ts

@@ -10,8 +10,11 @@ export type StreamLiveOptions = {
   WebSocketImpl?: typeof WebSocket
   onSubscribed?: (live: boolean) => void
   onError?: (message: string) => void
+  connectTimeoutMs?: number
 }
 
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000
+
 export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<InspectEvent> {
   const WS = opts.WebSocketImpl ?? WebSocket
   const ws = new WS(opts.url)
@@ -63,9 +66,11 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
     }
   })
 
-  // Settle on open OR on any terminal condition (error/close/abort). Resolving
-  // false here is what unblocks the connect gate when esc aborts mid-connect —
-  // otherwise `await onOpen` would hang forever and freeze the inspect CLI.
+  // Settle on open OR on any terminal condition (error/close/abort/timeout).
+  // Resolving false on abort/close/timeout is what unblocks the connect gate —
+  // otherwise `await onOpen` would hang forever and freeze the inspect CLI. The
+  // timeout bounds Bun/websocket states that neither open nor error promptly.
+  let connectTimer: ReturnType<typeof setTimeout> | null = null
   const onOpen = new Promise<boolean>((resolve, reject) => {
     ws.addEventListener('open', () => resolve(true), { once: true })
     ws.addEventListener('error', () => reject(new Error('websocket connection failed')), { once: true })
@@ -74,6 +79,8 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
       if (opts.signal.aborted) resolve(false)
       else opts.signal.addEventListener('abort', () => resolve(false), { once: true })
     }
+    const timeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
+    connectTimer = setTimeout(() => reject(new Error('websocket connect timed out')), timeoutMs)
   })
   ws.addEventListener('close', () => {
     closed = true
@@ -109,7 +116,14 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
     opened = await onOpen
   } catch (err) {
     closed = true
+    try {
+      ws.close()
+    } catch {
+      /* ignore */
+    }
     throw err
+  } finally {
+    if (connectTimer !== null) clearTimeout(connectTimer)
   }
   if (!opened || closed || opts.signal?.aborted === true) return
 

package/src/inspect/loop.ts

@@ -1,20 +1,21 @@
 import { runInspect, type RunInspectOptions, type RunInspectResult } from './index'
 
-export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
-  newEscSignal: () => AbortSignal
-  // Runs after every runInspect attempt settles. The caller disarms the raw-mode
-  // ESC listener here so the live tail releases stdin before clack re-opens the
-  // picker: an ESC-aborted tail leaves the listener armed (raw mode on, 'data'
-  // handler attached), and handing clack that flowing stream freezes the picker
-  // on SSH/Bun pseudo-TTYs.
-  afterEscStream?: () => void
+export type TailController = {
+  signal: AbortSignal
+  intent: () => 'back' | 'exit' | null
+  dispose: () => void
+}
+
+export type RunInspectLoopOptions = Omit<RunInspectOptions, 'signal'> & {
+  // Builds a fresh interaction scope for ONE live-tail attempt: a new
+  // AbortController plus a temporary raw-mode listener. The loop disposes it
+  // before the picker re-opens so clack always owns a clean, non-raw stdin —
+  // this is what replaces the old pause/resume-same-controller model.
+  createTailScope: () => TailController
 }
 
 export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
   let sessionArg = opts.sessionIdOrPrefix
-  // Remember the last session the user picked from the interactive picker so
-  // an ESC-back-to-picker re-opens with that row pre-selected. The picker
-  // receives this through the `initialSessionId` hint on its second arg.
   let lastPickedId: string | undefined
   const wrappedSelectSession: typeof opts.selectSession = async (sessions, selectOpts) => {
     const hint = selectOpts?.initialSessionId ?? lastPickedId
@@ -24,18 +25,23 @@ export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunIn
   }
 
   while (true) {
-    const escSignal = opts.newEscSignal()
-    const callOpts: RunInspectOptions = { ...opts, escSignal, selectSession: wrappedSelectSession }
-    if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
-    else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
-
+    const scope = opts.createTailScope()
     let result: RunInspectResult
     try {
+      const callOpts: RunInspectOptions = {
+        ...opts,
+        selectSession: wrappedSelectSession,
+        signal: scope.signal,
+      }
+      if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
+      else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
       result = await runInspect(callOpts)
     } finally {
-      opts.afterEscStream?.()
+      scope.dispose()
     }
+
     if (!result.ok) return result
+    if (scope.intent() === 'exit') return result
     if (result.escToPicker !== true) return result
     sessionArg = undefined
   }

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'