/**
 * MCP Client for Franklin.
 *
 * Connects to MCP servers, discovers tools, and wraps them as CapabilityHandlers.
 * Supports:
 *   - stdio transport (local subprocess)
 *   - StreamableHTTP transport (remote, with optional OAuth)
 *   - SSE transport (legacy remote)
 *
 * Per-server features:
 *   - `enabled_tools` / `disabled_tools` allowlist (mirrors Codex)
 *   - stderr piping into the franklin debug log so misconfigured servers can
 *     be diagnosed without dumping into the user's terminal
 *   - OAuth via the SDK's `OAuthClientProvider` contract; tokens persisted
 *     under `~/.blockrun/mcp/oauth/<server>.json`
 *   - connection status + last-error snapshot surfaced to `/mcp` command
 */
import type { CapabilityHandler } from '../agent/types.js';
export interface McpServerConfig {
    /** Transport type. `stdio` runs a local subprocess; `http` connects to a
     *  remote MCP server via StreamableHTTP (preferred) or SSE (legacy). */
    transport: 'stdio' | 'http' | 'sse';
    /** For stdio: command to run */
    command?: string;
    /** For stdio: arguments */
    args?: string[];
    /** For stdio / http: environment / extra headers passthrough */
    env?: Record<string, string>;
    /** For http / sse: server URL */
    url?: string;
    /** For http / sse: static request headers (use OAuth for dynamic auth) */
    headers?: Record<string, string>;
    /** Allowlist: only expose these tool names to the model (post-discovery).
     *  Wildcards not supported — match by exact tool short name. */
    enabled_tools?: string[];
    /** Denylist: hide these tool names. Applied after `enabled_tools`. */
    disabled_tools?: string[];
    /** Human-readable label */
    label?: string;
    /** Disable this server entirely */
    disabled?: boolean;
    /** Enable OAuth flow for http/sse transports. Set to a hint string
     *  (e.g. "interactive" or "device") or `true` for the default. */
    oauth?: boolean | {
        scopes?: string[];
        clientName?: string;
    };
}
export interface McpConfig {
    mcpServers: Record<string, McpServerConfig>;
}
export declare function connectMcpServers(config: McpConfig, debug?: boolean): Promise<CapabilityHandler[]>;
export declare function disconnectMcpServers(): Promise<void>;
export declare function getMcpServerInstructions(): string;
export interface McpServerStatus {
    name: string;
    transport: 'stdio' | 'http' | 'sse';
    toolCount: number;
    tools: string[];
    filtered: number;
    hasOAuth: boolean;
    oauthAuthorized: boolean;
}
export declare function listMcpServers(): McpServerStatus[];
export interface McpServerFailure {
    name: string;
    reason: string;
    transport: 'stdio' | 'http' | 'sse';
    stderrTail: string[];
}
export declare function listMcpFailures(): McpServerFailure[];
/** Most recent N stderr lines from a connected stdio MCP server (for `/mcp`). */
export declare function getMcpStderrTail(name: string): string[];