@forgewisp/mcp 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,230 @@
+import { FunctionDefinition, RiskTier } from '@forgewisp/core';
+export { FunctionDefinition, JSONSchema, JSONSchemaProperty, RiskTier, ToolContext } from '@forgewisp/core';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+export { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+export { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+/**
+ * Structural view of a Forgewisp agent: the two methods the MCP integration needs. The real
+ * `ForgewispAgent` (from `createAgent`) satisfies this structurally, so consumers pass their
+ * agent instance directly: `await registerMcpServer(agent, { ... })`. Declaring a structural
+ * subset (rather than importing the not-exported `ForgewispAgent` class) keeps this package
+ * decoupled from core's internals — same technique `apps/bundled-demo` uses for its `ToolMeta`.
+ */
+interface AgentLike {
+    /** Registers a tool. Throws at registration time for `write`/`destructive` tools when the
+     *  agent's `onConfirmRequired` is unset (core enforces this — see `packages/core/src/agent.ts`). */
+    registerFunction(def: FunctionDefinition): void;
+    /** Deregisters a tool by name. No-op if unknown. */
+    deregisterFunction(name: string): void;
+}
+/**
+ * Configuration for connecting an MCP server and adapting its tools into Forgewisp
+ * `FunctionDefinition`s.
+ */
+interface McpServerConfig {
+    /**
+     * Logical server name. Used as the default `toolNamePrefix` and as the audit/UI attribution
+     * suffix on each tool's description. Also identifies the server in error messages.
+     */
+    name: string;
+    /** Streamable HTTP endpoint URL of the MCP server. */
+    url: string;
+    /**
+     * Optional bearer token sent to the MCP endpoint as `Authorization: Bearer <apiKey>`. The
+     * header is omitted entirely when unset, so no-auth/proxy endpoints work — mirrors core's
+     * `HttpClient` (which only sends `Authorization` when an `apiKey` is configured). Mutually
+     * exclusive with `authProvider`; when both are set, `authProvider` wins and `apiKey` is ignored.
+     * Use this when you already hold an access token; use `authProvider` when the server requires a
+     * full OAuth flow to *obtain* one.
+     */
+    apiKey?: string;
+    /**
+     * OAuth client provider. When set, takes precedence over `apiKey` and drives the full OAuth 2.1
+     * authorization-code + PKCE flow via the SDK: RFC 9728 protected-resource discovery, RFC 8414
+     * authorization-server metadata discovery, dynamic client registration (RFC 7591) when the
+     * server supports it, token exchange, and refresh. The consumer owns browser-redirect plumbing
+     * and token storage by implementing `OAuthClientProvider`.
+     *
+     * On the first connect, if the server requires auth and no usable token exists, the SDK calls
+     * `authProvider.redirectToAuthorization(url)` and the connect returns `authState: 'pending'`
+     * with an empty `tools` array (instead of throwing). The consumer completes the redirect-back and
+     * calls `finishAuth(code)` on the handle (or, after a page reload, calls
+     * `createMcpTools`/`registerMcpServer` again with `options.authorizationCode`). See `mcp.ts` for
+     * why a fresh transport is built on resume (the SDK cannot re-`connect` a spent transport).
+     */
+    authProvider?: OAuthClientProvider;
+    /** Per-call timeout for MCP `listTools`/`callTool` requests, in milliseconds. Default 60_000. */
+    requestTimeoutMs?: number;
+    /** Prefix for the registered (prefixed) tool names. Default: `config.name`. */
+    toolNamePrefix?: string;
+    /** Default risk tier for tools not listed in `tierOverrides`. Default: `'read'`. */
+    defaultTier?: RiskTier;
+    /** Map of original MCP tool name → risk tier (overrides `defaultTier` for that tool). */
+    tierOverrides?: Record<string, RiskTier>;
+    /** Allowlist of original MCP tool names to register; all others are skipped. */
+    onlyTools?: string[];
+    /** Blocklist of original MCP tool names to skip. */
+    excludeTools?: string[];
+    /**
+     * Whether the agent has `onConfirmRequired` configured. Required to be `true` when any
+     * resolved tool tier is `write` or `destructive`; `registerMcpServer` throws a clear error
+     * up front (before registering anything) otherwise — so a tier mismatch never leaves a
+     * partially-registered server. Core's own registration-time invariant still fires as a
+     * backstop inside `agent.registerFunction`.
+     */
+    hasConfirmation?: boolean;
+}
+/** Handle returned by `registerMcpServer` for managing a server's lifecycle. */
+interface McpServerHandle {
+    /** The prefixed tool names that were registered on the agent. Empty while `authState` is
+     *  `'pending'` (tools are not listed until auth completes). */
+    toolNames: string[];
+    /** Authorization state. `'pending'` means the server requires OAuth and the consumer must complete
+     *  the redirect-back via `finishAuth` (or resume with `options.authorizationCode`). */
+    authState: McpAuthState;
+    /**
+     * Complete the OAuth redirect-back: exchange `authorizationCode` for tokens (via the provider),
+     * build a fresh transport, reconnect, list the server's tools, run the `hasConfirmation`
+     * preflight, and register the tools on the agent. Mutates `toolNames`/`authState` in place.
+     *
+     * Rejects if already authorized or closed, or if the post-auth preflight fails (in which case
+     * nothing remains registered). Idempotent guard: a second `finishAuth` is a no-op.
+     */
+    finishAuth(authorizationCode: string): Promise<void>;
+    /** Deregisters all of this server's tools from the agent and disconnects from the MCP server. */
+    close(): Promise<void>;
+}
+/** Authorization state of a connected MCP server. */
+type McpAuthState = 'authorized' | 'pending';
+/**
+ * Options for `createMcpTools` / `registerMcpServer`.
+ */
+interface McpConnectOptions {
+    /**
+     * Resume path: an authorization code obtained from the redirect-back after a page reload (or a
+     * blocked-popup same-tab navigation). When set alongside `config.authProvider`, the code is
+     * exchanged for tokens on a fresh transport *before* connecting, so the (re)connect reads the
+     * saved token and returns `authState: 'authorized'` directly — skipping the pending state.
+     * Ignored when `authProvider` is not set.
+     */
+    authorizationCode?: string;
+    /**
+     * @internal Test seam to inject a non-HTTP transport (e.g. `InMemoryTransport` or an OAuth-gated
+     *   fake), so tests never dynamic-import `StreamableHTTPClientTransport`. May be a single
+     *   `Transport` (used once for the initial connect — fine for non-OAuth tests, where `finishAuth`
+     *   is never called) or a factory `() => Transport | Promise<Transport>` invoked each time a
+     *   transport is needed (initial connect AND each `finishAuth` reconnect), which is how OAuth
+     *   tests supply a fresh gated transport that shares one in-memory pipe. Not part of the stable
+     *   public contract.
+     */
+    transport?: Transport | (() => Transport | Promise<Transport>);
+}
+
+/**
+ * MCP → Forgewisp adapter.
+ *
+ * Connects to an MCP server over the Streamable HTTP transport, lists its tools, and adapts
+ * each into a Forgewisp `FunctionDefinition` that is registered through the agent's existing
+ * `registerFunction` path. Because registration goes through core unchanged, the registry,
+ * Ajv validation, the two-phase executor, the `onConfirmRequired` confirmation invariant, the
+ * audit log, and `runToolLoop` all apply to MCP tools for free — MCP becomes just another source
+ * of `FunctionDefinition`s.
+ *
+ * The adapter is layered so the mapping is unit-testable without a network:
+ *   - `adaptMcpTool` / `adaptMcpTools` — pure given a `McpClient` (the test seam; a plain fake
+ *     object implementing `callTool` is enough).
+ *   - `connectMcpServer` — builds the SDK `Client` + `StreamableHTTPClientTransport`.
+ *   - `createMcpTools` / `registerMcpServer` — the public wiring.
+ *
+ * ── Schema handling ──────────────────────────────────────────────────────────
+ * MCP `inputSchema` is full draft-07 JSON Schema. Forgewisp's `JSONSchema` type (in core) is a
+ * deliberately narrow subset enforcing strict hand-authored schemas in `@forgewisp/bundled-tools`;
+ * we do NOT widen it. The adapter casts the raw `inputSchema` to `JSONSchema` at the boundary.
+ * Runtime is correct: core's Ajv is `strict: false` and validates draft-07 (`$ref`/`enum`/`oneOf`
+ * etc.), the compiled validator is cached per schema-object identity, and the wire payload sent
+ * to the LLM carries the full schema, which OpenAI-compatible models accept. Limitation: any
+ * external `$ref` (not present in well-formed MCP schemas) won't resolve.
+ *
+ * ── Risk tiers ────────────────────────────────────────────────────────────────
+ * MCP has no risk-tier concept. Tiers come entirely from `McpServerConfig` (`defaultTier` +
+ * `tierOverrides`); MCP `annotations.readOnlyHint`/`destructiveHint` are informational only and
+ * deliberately NOT auto-mapped — the consumer owns the security boundary.
+ *
+ * ── Abort ─────────────────────────────────────────────────────────────────────
+ * The parent run's `AbortSignal` is threaded into handlers by core's executor via `ToolContext`.
+ * The handler forwards it to `client.callTool` (merged with a per-server timeout), so aborting
+ * the parent run aborts in-flight MCP calls.
+ *
+ * ── OAuth ─────────────────────────────────────────────────────────────────────
+ * `McpServerConfig.authProvider` (an SDK `OAuthClientProvider`) takes precedence over `apiKey` and
+ * drives the full OAuth 2.1 authorization-code + PKCE flow (RFC 9728 / 8414 discovery, dynamic client
+ * registration, token exchange, refresh) via the SDK transport — the consumer only implements the
+ * provider (browser-redirect plumbing + token storage). `client/auth.js` is dynamically imported
+ * only on the OAuth path; non-OAuth consumers never load it.
+ *
+ * State machine: the first `connect` that needs auth has the SDK call
+ * `authProvider.redirectToAuthorization(url)` and then throw `UnauthorizedError` from `connect`.
+ * `Client.connect` catches that, calls `void this.close()`, and rethrows. The transport is now
+ * *spent* — `close()` aborts its `AbortController` but does not null it, so a second `start()`
+ * throws "already started". **The same transport cannot be re-`connect`ed.** So this adapter
+ * catches `UnauthorizedError` (via `instanceof`, dynamically importing the class only on this path —
+ * the SDK's error doesn't set a custom `name`, so a name check won't work) and returns
+ * `authState: 'pending'` (empty tools) instead of throwing, keeping the spent transport+client only
+ * long enough to call `transport.finishAuth(code)` (which just calls `auth()` to exchange the code
+ * and save tokens into the provider — it does not require `start()`). `finishAuth` then builds a
+ * **fresh** transport + client whose `connect` reads the saved token via `provider.tokens()` and
+ * succeeds. The same "finishAuth-then-fresh-connect" pattern powers the resume path
+ * (`options.authorizationCode`), which exchanges the code on a single fresh transport *before*
+ * connecting.
+ *
+ * For `registerMcpServer`, the `hasConfirmation` preflight runs only once tools are listed — i.e.
+ * after auth completes (deferred when `authState` is `'pending'`), mirroring the non-OAuth path.
+ */
+
+/** Shape returned by `createMcpTools`: the adapted tools, a closer, and (for OAuth) the auth flow. */
+interface McpToolsResult {
+    /** The adapted `FunctionDefinition`s. Empty while `authState` is `'pending'`; mutated in place by
+     *  `finishAuth` once auth completes, so the caller's reference stays valid. */
+    tools: FunctionDefinition[];
+    /** Authorization state. `'pending'` means the server requires OAuth and `finishAuth` (or a
+     *  resume via `options.authorizationCode`) is needed before tools are available. */
+    authState: McpAuthState;
+    /** Disconnects the underlying client. Idempotent. */
+    close: () => Promise<void>;
+    /** Completes the OAuth redirect-back. See `McpServerHandle.finishAuth`. */
+    finishAuth: (authorizationCode: string) => Promise<void>;
+}
+/**
+ * Connect to an MCP server, list its tools, and adapt them into `FunctionDefinition`s without
+ * touching any agent. Useful for custom registration or `ToolSet` composition. The returned
+ * `close()` disconnects the underlying client.
+ *
+ * OAuth: when `config.authProvider` is set and the server requires auth, the first connect returns
+ * `authState: 'pending'` with an empty `tools` array (the SDK already redirected the user agent).
+ * Call `finishAuth(code)` after the redirect-back to exchange the code and populate `tools`, or pass
+ * `options.authorizationCode` to resume in one shot after a page reload.
+ *
+ * @internal `options.transport` is a test seam to inject a non-HTTP transport; not part of the
+ *   stable public contract.
+ */
+declare function createMcpTools(config: McpServerConfig, options?: McpConnectOptions): Promise<McpToolsResult>;
+/**
+ * Connect to an MCP server and register all of its (adapted) tools on the given agent. Returns an
+ * `McpServerHandle` whose `close()` deregisters every tool and disconnects.
+ *
+ * Confirmation preflight: before registering anything, if any adapted tool resolves to
+ * `write`/`destructive` and `config.hasConfirmation` is not `true`, the client is closed and a
+ * clear error is thrown — so a tier mismatch never leaves a partially-registered server. Core's
+ * own registration-time invariant still fires as a backstop inside `agent.registerFunction`.
+ *
+ * OAuth: when the first connect returns `authState: 'pending'`, no tools are registered yet and the
+ * preflight is deferred until `handle.finishAuth(code)` lists the tools. If the post-auth preflight
+ * fails, `finishAuth` deregisters anything registered, disconnects, and throws the same error.
+ *
+ * @internal `options.transport` is a test seam to inject a non-HTTP transport.
+ */
+declare function registerMcpServer(agent: AgentLike, config: McpServerConfig, options?: McpConnectOptions): Promise<McpServerHandle>;
+
+export { type AgentLike, type McpAuthState, type McpConnectOptions, type McpServerConfig, type McpServerHandle, type McpToolsResult, createMcpTools, registerMcpServer };

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+import { FunctionDefinition, RiskTier } from '@forgewisp/core';
+export { FunctionDefinition, JSONSchema, JSONSchemaProperty, RiskTier, ToolContext } from '@forgewisp/core';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+export { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+export { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+/**
+ * Structural view of a Forgewisp agent: the two methods the MCP integration needs. The real
+ * `ForgewispAgent` (from `createAgent`) satisfies this structurally, so consumers pass their
+ * agent instance directly: `await registerMcpServer(agent, { ... })`. Declaring a structural
+ * subset (rather than importing the not-exported `ForgewispAgent` class) keeps this package
+ * decoupled from core's internals — same technique `apps/bundled-demo` uses for its `ToolMeta`.
+ */
+interface AgentLike {
+    /** Registers a tool. Throws at registration time for `write`/`destructive` tools when the
+     *  agent's `onConfirmRequired` is unset (core enforces this — see `packages/core/src/agent.ts`). */
+    registerFunction(def: FunctionDefinition): void;
+    /** Deregisters a tool by name. No-op if unknown. */
+    deregisterFunction(name: string): void;
+}
+/**
+ * Configuration for connecting an MCP server and adapting its tools into Forgewisp
+ * `FunctionDefinition`s.
+ */
+interface McpServerConfig {
+    /**
+     * Logical server name. Used as the default `toolNamePrefix` and as the audit/UI attribution
+     * suffix on each tool's description. Also identifies the server in error messages.
+     */
+    name: string;
+    /** Streamable HTTP endpoint URL of the MCP server. */
+    url: string;
+    /**
+     * Optional bearer token sent to the MCP endpoint as `Authorization: Bearer <apiKey>`. The
+     * header is omitted entirely when unset, so no-auth/proxy endpoints work — mirrors core's
+     * `HttpClient` (which only sends `Authorization` when an `apiKey` is configured). Mutually
+     * exclusive with `authProvider`; when both are set, `authProvider` wins and `apiKey` is ignored.
+     * Use this when you already hold an access token; use `authProvider` when the server requires a
+     * full OAuth flow to *obtain* one.
+     */
+    apiKey?: string;
+    /**
+     * OAuth client provider. When set, takes precedence over `apiKey` and drives the full OAuth 2.1
+     * authorization-code + PKCE flow via the SDK: RFC 9728 protected-resource discovery, RFC 8414
+     * authorization-server metadata discovery, dynamic client registration (RFC 7591) when the
+     * server supports it, token exchange, and refresh. The consumer owns browser-redirect plumbing
+     * and token storage by implementing `OAuthClientProvider`.
+     *
+     * On the first connect, if the server requires auth and no usable token exists, the SDK calls
+     * `authProvider.redirectToAuthorization(url)` and the connect returns `authState: 'pending'`
+     * with an empty `tools` array (instead of throwing). The consumer completes the redirect-back and
+     * calls `finishAuth(code)` on the handle (or, after a page reload, calls
+     * `createMcpTools`/`registerMcpServer` again with `options.authorizationCode`). See `mcp.ts` for
+     * why a fresh transport is built on resume (the SDK cannot re-`connect` a spent transport).
+     */
+    authProvider?: OAuthClientProvider;
+    /** Per-call timeout for MCP `listTools`/`callTool` requests, in milliseconds. Default 60_000. */
+    requestTimeoutMs?: number;
+    /** Prefix for the registered (prefixed) tool names. Default: `config.name`. */
+    toolNamePrefix?: string;
+    /** Default risk tier for tools not listed in `tierOverrides`. Default: `'read'`. */
+    defaultTier?: RiskTier;
+    /** Map of original MCP tool name → risk tier (overrides `defaultTier` for that tool). */
+    tierOverrides?: Record<string, RiskTier>;
+    /** Allowlist of original MCP tool names to register; all others are skipped. */
+    onlyTools?: string[];
+    /** Blocklist of original MCP tool names to skip. */
+    excludeTools?: string[];
+    /**
+     * Whether the agent has `onConfirmRequired` configured. Required to be `true` when any
+     * resolved tool tier is `write` or `destructive`; `registerMcpServer` throws a clear error
+     * up front (before registering anything) otherwise — so a tier mismatch never leaves a
+     * partially-registered server. Core's own registration-time invariant still fires as a
+     * backstop inside `agent.registerFunction`.
+     */
+    hasConfirmation?: boolean;
+}
+/** Handle returned by `registerMcpServer` for managing a server's lifecycle. */
+interface McpServerHandle {
+    /** The prefixed tool names that were registered on the agent. Empty while `authState` is
+     *  `'pending'` (tools are not listed until auth completes). */
+    toolNames: string[];
+    /** Authorization state. `'pending'` means the server requires OAuth and the consumer must complete
+     *  the redirect-back via `finishAuth` (or resume with `options.authorizationCode`). */
+    authState: McpAuthState;
+    /**
+     * Complete the OAuth redirect-back: exchange `authorizationCode` for tokens (via the provider),
+     * build a fresh transport, reconnect, list the server's tools, run the `hasConfirmation`
+     * preflight, and register the tools on the agent. Mutates `toolNames`/`authState` in place.
+     *
+     * Rejects if already authorized or closed, or if the post-auth preflight fails (in which case
+     * nothing remains registered). Idempotent guard: a second `finishAuth` is a no-op.
+     */
+    finishAuth(authorizationCode: string): Promise<void>;
+    /** Deregisters all of this server's tools from the agent and disconnects from the MCP server. */
+    close(): Promise<void>;
+}
+/** Authorization state of a connected MCP server. */
+type McpAuthState = 'authorized' | 'pending';
+/**
+ * Options for `createMcpTools` / `registerMcpServer`.
+ */
+interface McpConnectOptions {
+    /**
+     * Resume path: an authorization code obtained from the redirect-back after a page reload (or a
+     * blocked-popup same-tab navigation). When set alongside `config.authProvider`, the code is
+     * exchanged for tokens on a fresh transport *before* connecting, so the (re)connect reads the
+     * saved token and returns `authState: 'authorized'` directly — skipping the pending state.
+     * Ignored when `authProvider` is not set.
+     */
+    authorizationCode?: string;
+    /**
+     * @internal Test seam to inject a non-HTTP transport (e.g. `InMemoryTransport` or an OAuth-gated
+     *   fake), so tests never dynamic-import `StreamableHTTPClientTransport`. May be a single
+     *   `Transport` (used once for the initial connect — fine for non-OAuth tests, where `finishAuth`
+     *   is never called) or a factory `() => Transport | Promise<Transport>` invoked each time a
+     *   transport is needed (initial connect AND each `finishAuth` reconnect), which is how OAuth
+     *   tests supply a fresh gated transport that shares one in-memory pipe. Not part of the stable
+     *   public contract.
+     */
+    transport?: Transport | (() => Transport | Promise<Transport>);
+}
+
+/**
+ * MCP → Forgewisp adapter.
+ *
+ * Connects to an MCP server over the Streamable HTTP transport, lists its tools, and adapts
+ * each into a Forgewisp `FunctionDefinition` that is registered through the agent's existing
+ * `registerFunction` path. Because registration goes through core unchanged, the registry,
+ * Ajv validation, the two-phase executor, the `onConfirmRequired` confirmation invariant, the
+ * audit log, and `runToolLoop` all apply to MCP tools for free — MCP becomes just another source
+ * of `FunctionDefinition`s.
+ *
+ * The adapter is layered so the mapping is unit-testable without a network:
+ *   - `adaptMcpTool` / `adaptMcpTools` — pure given a `McpClient` (the test seam; a plain fake
+ *     object implementing `callTool` is enough).
+ *   - `connectMcpServer` — builds the SDK `Client` + `StreamableHTTPClientTransport`.
+ *   - `createMcpTools` / `registerMcpServer` — the public wiring.
+ *
+ * ── Schema handling ──────────────────────────────────────────────────────────
+ * MCP `inputSchema` is full draft-07 JSON Schema. Forgewisp's `JSONSchema` type (in core) is a
+ * deliberately narrow subset enforcing strict hand-authored schemas in `@forgewisp/bundled-tools`;
+ * we do NOT widen it. The adapter casts the raw `inputSchema` to `JSONSchema` at the boundary.
+ * Runtime is correct: core's Ajv is `strict: false` and validates draft-07 (`$ref`/`enum`/`oneOf`
+ * etc.), the compiled validator is cached per schema-object identity, and the wire payload sent
+ * to the LLM carries the full schema, which OpenAI-compatible models accept. Limitation: any
+ * external `$ref` (not present in well-formed MCP schemas) won't resolve.
+ *
+ * ── Risk tiers ────────────────────────────────────────────────────────────────
+ * MCP has no risk-tier concept. Tiers come entirely from `McpServerConfig` (`defaultTier` +
+ * `tierOverrides`); MCP `annotations.readOnlyHint`/`destructiveHint` are informational only and
+ * deliberately NOT auto-mapped — the consumer owns the security boundary.
+ *
+ * ── Abort ─────────────────────────────────────────────────────────────────────
+ * The parent run's `AbortSignal` is threaded into handlers by core's executor via `ToolContext`.
+ * The handler forwards it to `client.callTool` (merged with a per-server timeout), so aborting
+ * the parent run aborts in-flight MCP calls.
+ *
+ * ── OAuth ─────────────────────────────────────────────────────────────────────
+ * `McpServerConfig.authProvider` (an SDK `OAuthClientProvider`) takes precedence over `apiKey` and
+ * drives the full OAuth 2.1 authorization-code + PKCE flow (RFC 9728 / 8414 discovery, dynamic client
+ * registration, token exchange, refresh) via the SDK transport — the consumer only implements the
+ * provider (browser-redirect plumbing + token storage). `client/auth.js` is dynamically imported
+ * only on the OAuth path; non-OAuth consumers never load it.
+ *
+ * State machine: the first `connect` that needs auth has the SDK call
+ * `authProvider.redirectToAuthorization(url)` and then throw `UnauthorizedError` from `connect`.
+ * `Client.connect` catches that, calls `void this.close()`, and rethrows. The transport is now
+ * *spent* — `close()` aborts its `AbortController` but does not null it, so a second `start()`
+ * throws "already started". **The same transport cannot be re-`connect`ed.** So this adapter
+ * catches `UnauthorizedError` (via `instanceof`, dynamically importing the class only on this path —
+ * the SDK's error doesn't set a custom `name`, so a name check won't work) and returns
+ * `authState: 'pending'` (empty tools) instead of throwing, keeping the spent transport+client only
+ * long enough to call `transport.finishAuth(code)` (which just calls `auth()` to exchange the code
+ * and save tokens into the provider — it does not require `start()`). `finishAuth` then builds a
+ * **fresh** transport + client whose `connect` reads the saved token via `provider.tokens()` and
+ * succeeds. The same "finishAuth-then-fresh-connect" pattern powers the resume path
+ * (`options.authorizationCode`), which exchanges the code on a single fresh transport *before*
+ * connecting.
+ *
+ * For `registerMcpServer`, the `hasConfirmation` preflight runs only once tools are listed — i.e.
+ * after auth completes (deferred when `authState` is `'pending'`), mirroring the non-OAuth path.
+ */
+
+/** Shape returned by `createMcpTools`: the adapted tools, a closer, and (for OAuth) the auth flow. */
+interface McpToolsResult {
+    /** The adapted `FunctionDefinition`s. Empty while `authState` is `'pending'`; mutated in place by
+     *  `finishAuth` once auth completes, so the caller's reference stays valid. */
+    tools: FunctionDefinition[];
+    /** Authorization state. `'pending'` means the server requires OAuth and `finishAuth` (or a
+     *  resume via `options.authorizationCode`) is needed before tools are available. */
+    authState: McpAuthState;
+    /** Disconnects the underlying client. Idempotent. */
+    close: () => Promise<void>;
+    /** Completes the OAuth redirect-back. See `McpServerHandle.finishAuth`. */
+    finishAuth: (authorizationCode: string) => Promise<void>;
+}
+/**
+ * Connect to an MCP server, list its tools, and adapt them into `FunctionDefinition`s without
+ * touching any agent. Useful for custom registration or `ToolSet` composition. The returned
+ * `close()` disconnects the underlying client.
+ *
+ * OAuth: when `config.authProvider` is set and the server requires auth, the first connect returns
+ * `authState: 'pending'` with an empty `tools` array (the SDK already redirected the user agent).
+ * Call `finishAuth(code)` after the redirect-back to exchange the code and populate `tools`, or pass
+ * `options.authorizationCode` to resume in one shot after a page reload.
+ *
+ * @internal `options.transport` is a test seam to inject a non-HTTP transport; not part of the
+ *   stable public contract.
+ */
+declare function createMcpTools(config: McpServerConfig, options?: McpConnectOptions): Promise<McpToolsResult>;
+/**
+ * Connect to an MCP server and register all of its (adapted) tools on the given agent. Returns an
+ * `McpServerHandle` whose `close()` deregisters every tool and disconnects.
+ *
+ * Confirmation preflight: before registering anything, if any adapted tool resolves to
+ * `write`/`destructive` and `config.hasConfirmation` is not `true`, the client is closed and a
+ * clear error is thrown — so a tier mismatch never leaves a partially-registered server. Core's
+ * own registration-time invariant still fires as a backstop inside `agent.registerFunction`.
+ *
+ * OAuth: when the first connect returns `authState: 'pending'`, no tools are registered yet and the
+ * preflight is deferred until `handle.finishAuth(code)` lists the tools. If the post-auth preflight
+ * fails, `finishAuth` deregisters anything registered, disconnects, and throws the same error.
+ *
+ * @internal `options.transport` is a test seam to inject a non-HTTP transport.
+ */
+declare function registerMcpServer(agent: AgentLike, config: McpServerConfig, options?: McpConnectOptions): Promise<McpServerHandle>;
+
+export { type AgentLike, type McpAuthState, type McpConnectOptions, type McpServerConfig, type McpServerHandle, type McpToolsResult, createMcpTools, registerMcpServer };