zidane/mcp

Connect to MCP servers and discover their tools.

Each tool is namespaced as mcp_{serverName}_{toolName} to avoid collisions with agent tools or tools from other servers.

function connectMcpServers(
  configs: McpServerConfig[],
  _clientFactory?: McpClientFactory,
  hooks?: Hookable<AgentHooks, HookKeys<AgentHooks>>,
  options?: ConnectMcpServersOptions,
): Promise<McpConnection>

import { connectMcpServers } from 'zidane/mcp'

const connection = await connectMcpServers([
  { name: 'fs', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
])
console.log(Object.keys(connection.tools))
await connection.close()

Expanded COPY of a server config for runtime use — ${VAR} placeholders resolved across every string field that can carry secrets or machine-specific paths (command, args, env/header values, url, cwd).

Deliberately NOT part of normalizeMcpServers: normalized configs are round-tripped back to disk by config writers (e.g. the Claude import copies parsed entries into zidane-owned mcps.json), and expanding there would MATERIALIZE resolved tokens into files. Expansion happens only at the transport boundary (createTransport, the login flow's mirror) — secrets exist in the connecting process's memory and nowhere else.

function expandMcpConfigEnv(
  config: McpServerConfig,
  env?: Record<string, string | undefined>,
): McpServerConfig

The transport-reachability rule for a remote MCP endpoint: HTTPS anywhere, plaintext HTTP only when it stays on the machine, nothing else.

THE single encoding of that policy. It's enforced at two points on opposite sides of the plugin boundary — once when validating a plugin's mcp.json (plugins/mcp.ts), and again per redirect hop inside originPinnedFetch — and those two must never disagree. If they did, a URL the loader refused could still be reached by redirect, which is the exact hole the pinning exists to close. Relaxing the rule (private ranges, *.localhost, …) is then a one-line change that both sites inherit.

Scheme and host only. Authoring rules that apply to a CONFIGURED url but have no meaning for a redirect target — no userinfo, no fragment — stay with the loader.

function isAllowedRemoteUrl(url: URL): boolean

Normalize MCP CallToolResult.content to zidane's [] shape.

Handles the MCP content block types:

• text → preserved as {type:'text', text}
• image → preserved as {type:'image', mediaType, data} (MCP uses mimeType)
• audio → {type:'audio', mediaType, data}; mediaType reconciled/sniffed when the declared mimeType is missing or not an audio/* type
• video → {type:'video', mediaType, data} (non-standard, by analogy)
• resource with embedded text → flattened to a text block
• resource with embedded blob → routed to image/audio/video by sniffing bytes first, with declared mimeType as a fallback when bytes are unidentifiable (it's OPTIONAL on EmbeddedResource per the MCP spec, and often imprecise)
• Any unrecognized block → JSON-stringified fallback text block (lossy but safe)

Returns null when the input is not an array — callers should fall back to an empty result in that case.

function normalizeMcpBlocks(content: unknown): ToolResultContent[] | null

Normalize MCP server configs from any common shape to McpServerConfig[].

Accepts:

• McpServerConfig[] — zidane native (pass-through).
• McpServerConfig — a single config object (wrapped to a 1-element array).
• Record<string, RawShape> — name-keyed map (common in host-SDK configs), where the key is the server name.
• Mixed shapes with type vs transport, httpUrl/sseUrl vs url.

Returns [] when input is nullish. Throws a descriptive error when the transport cannot be inferred from a given entry, or when the input shape is unsupported.

function normalizeMcpServers(input: unknown): McpServerConfig[]

Wrap baseFetch so headerNames are dropped on any hop that leaves the origin of configuredUrl, and so a redirect cannot downgrade the session to cleartext.

authorization is ALWAYS protected, whether or not the caller listed it. The MCP SDK's OAuth provider injects that header per request rather than through McpServerConfig.headers — bootstrapServer attaches a provider to a flagless server whenever stored tokens exist — so a strip list derived only from the configured header names would leave the bearer token exposed on exactly the servers that have one.

function originPinnedFetch(
  configuredUrl: string,
  headerNames: readonly string[],
  baseFetch?: PinnedFetch,
): PinnedFetch

The config a transport is actually built from.

${VAR} placeholders resolve HERE, not at normalize time — see expandMcpConfigEnv for why (config writers round-trip normalized configs to disk; expanded secrets must never ride along).

A preExpanded config skips the pass entirely. The Agent Plugins loader has already substituted the only two placeholders that spec permits, in only the three fields it permits, so a second pass would both widen the scope (into command / url / headers) and let an ambient PLUGIN_ROOT env var reach text the spec says stays literal. See McpServerConfig.preExpanded.

function resolveTransportConfig(config: McpServerConfig): McpServerConfig

Lossy flattener — converts MCP CallToolResult.content blocks to a single string. Text blocks are extracted; non-text blocks are JSON-stringified.

Use this only at UI / log boundaries that require a string. The agent loop itself routes through normalizeMcpBlocks so image blocks survive into provider-native tool_result content (Anthropic blocks, OpenAI companion-user-message).

function resultToString(content: unknown): string

The fetch shape this wrapper supports — deliberately narrower than typeof fetch, matching the MCP SDK's FetchLike.

A Request input is NOT accepted: the wrapper rebuilds each hop from init, so it would silently drop a Request's method, headers and body and issue a bare credential-less GET. Narrowing the type makes that shape unrepresentable rather than a quiet failure on a security-relevant helper. Both SDK transports only ever pass a URL plus init.

type PinnedFetch = (url: string | URL, init?: RequestInit) => Promise<Response>