@frontmcp/sdk 0.7.2 → 0.8.0

package/direct/direct-server.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DirectMcpServerImpl - Implementation of DirectMcpServer
+ *
+ * Provides programmatic access to FrontMCP servers by bypassing the HTTP transport
+ * layer and invoking flows directly on the Scope instance.
+ */
+import type { ListToolsResult, CallToolResult, ListResourcesResult, ReadResourceResult, ListPromptsResult, GetPromptResult, ListResourceTemplatesResult } from '@modelcontextprotocol/sdk/types.js';
+import type { DirectMcpServer, DirectCallOptions } from './direct.types';
+import type { Scope } from '../scope/scope.instance';
+/**
+ * Implementation of DirectMcpServer that bypasses HTTP transport
+ * and invokes flows directly on a Scope instance.
+ */
+export declare class DirectMcpServerImpl implements DirectMcpServer {
+    private readonly scope;
+    readonly ready: Promise<void>;
+    private _isDisposed;
+    private readonly defaultSessionId;
+    constructor(scope: Scope);
+    /**
+     * Build the MCP handler context that flows expect.
+     * This simulates what the transport layer creates from HTTP request.
+     */
+    private buildHandlerContext;
+    /**
+     * Run a flow and handle FlowControl exceptions.
+     */
+    private runFlow;
+    listTools(options?: DirectCallOptions): Promise<ListToolsResult>;
+    callTool(name: string, args?: Record<string, unknown>, options?: DirectCallOptions): Promise<CallToolResult>;
+    listResources(options?: DirectCallOptions): Promise<ListResourcesResult>;
+    listResourceTemplates(options?: DirectCallOptions): Promise<ListResourceTemplatesResult>;
+    readResource(uri: string, options?: DirectCallOptions): Promise<ReadResourceResult>;
+    listPrompts(options?: DirectCallOptions): Promise<ListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string>, options?: DirectCallOptions): Promise<GetPromptResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=direct-server.d.ts.map

package/direct/direct-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-server.d.ts","sourceRoot":"","sources":["../../src/direct/direct-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAA4C,MAAM,gBAAgB,CAAC;AACnH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAsCrD;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,KAAK,EAAE,KAAK;IAMxB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;OAEG;YACW,OAAO;IAmCf,SAAS,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIhE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAY5G,aAAa,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQxE,qBAAqB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAQxF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYnF,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAY7G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAc/B"}

package/direct/direct.types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Direct MCP Server - Types and Interfaces
+ *
+ * Provides programmatic access to FrontMCP servers without HTTP/stdio transports.
+ * Useful for embedding MCP servers in existing applications, testing, and agent backends.
+ */
+import type { ListToolsResult, CallToolResult, ListResourcesResult, ReadResourceResult, ListPromptsResult, GetPromptResult, ListResourceTemplatesResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Auth context for direct server invocation.
+ * Simulates what would come from JWT validation in the HTTP layer.
+ */
+export interface DirectAuthContext {
+    /** Session ID for context tracking (auto-generated if not provided) */
+    sessionId?: string;
+    /** User/client token for authorization (e.g., JWT) */
+    token?: string;
+    /** User claims (extracted from token) */
+    user?: {
+        sub?: string;
+        [key: string]: unknown;
+    };
+    /** Additional auth info (claims, scopes, etc.) */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Request metadata for direct calls.
+ */
+export interface DirectRequestMetadata {
+    /** User-Agent string */
+    userAgent?: string;
+    /** Client IP address */
+    clientIp?: string;
+    /** Custom headers matching x-frontmcp-* pattern */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * Options for direct method calls.
+ */
+export interface DirectCallOptions {
+    /** Auth context to inject (simulates JWT header) */
+    authContext?: DirectAuthContext;
+    /** Request metadata */
+    metadata?: DirectRequestMetadata;
+}
+/**
+ * Direct MCP server interface - bypasses HTTP transport layer.
+ *
+ * Provides programmatic access to MCP operations (tools, resources, prompts)
+ * without requiring HTTP infrastructure.
+ *
+ * @example
+ * ```typescript
+ * import { FrontMcpInstance } from '@frontmcp/sdk';
+ *
+ * const server = await FrontMcpInstance.createDirect({
+ *   info: { name: 'MyServer', version: '1.0.0' },
+ *   apps: [MyApp],
+ * });
+ *
+ * // List all tools
+ * const { tools } = await server.listTools();
+ *
+ * // Call a tool with auth context
+ * const result = await server.callTool('my-tool', { input: 'value' }, {
+ *   authContext: { token: 'jwt-token', sessionId: 'user-123' }
+ * });
+ *
+ * // Cleanup when done
+ * await server.dispose();
+ * ```
+ */
+export interface DirectMcpServer {
+    /** Ready promise - resolves when server is initialized */
+    readonly ready: Promise<void>;
+    /**
+     * List all available tools.
+     *
+     * @param options - Optional call options with auth context
+     * @returns List of tool definitions
+     */
+    listTools(options?: DirectCallOptions): Promise<ListToolsResult>;
+    /**
+     * Call a tool with arguments.
+     *
+     * @param name - Tool name
+     * @param args - Tool arguments
+     * @param options - Optional call options with auth context
+     * @returns Tool execution result
+     */
+    callTool(name: string, args?: Record<string, unknown>, options?: DirectCallOptions): Promise<CallToolResult>;
+    /**
+     * List all available resources.
+     *
+     * @param options - Optional call options with auth context
+     * @returns List of resource definitions
+     */
+    listResources(options?: DirectCallOptions): Promise<ListResourcesResult>;
+    /**
+     * List all available resource templates.
+     *
+     * @param options - Optional call options with auth context
+     * @returns List of resource template definitions
+     */
+    listResourceTemplates(options?: DirectCallOptions): Promise<ListResourceTemplatesResult>;
+    /**
+     * Read a resource by URI.
+     *
+     * @param uri - Resource URI
+     * @param options - Optional call options with auth context
+     * @returns Resource content
+     */
+    readResource(uri: string, options?: DirectCallOptions): Promise<ReadResourceResult>;
+    /**
+     * List all available prompts.
+     *
+     * @param options - Optional call options with auth context
+     * @returns List of prompt definitions
+     */
+    listPrompts(options?: DirectCallOptions): Promise<ListPromptsResult>;
+    /**
+     * Get a prompt with arguments.
+     *
+     * @param name - Prompt name
+     * @param args - Prompt arguments
+     * @param options - Optional call options with auth context
+     * @returns Prompt content with messages
+     */
+    getPrompt(name: string, args?: Record<string, string>, options?: DirectCallOptions): Promise<GetPromptResult>;
+    /**
+     * Dispose the server and cleanup resources.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=direct.types.d.ts.map

package/direct/direct.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct.types.d.ts","sourceRoot":"","sources":["../../src/direct/direct.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE;QACL,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,uBAAuB;IACvB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAM9B;;;;;OAKG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEjE;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAM7G;;;;;OAKG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,qBAAqB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAEzF;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAMpF;;;;;OAKG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAErE;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAM9G;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/direct/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Direct MCP Server Module
+ *
+ * Provides programmatic access to FrontMCP servers without HTTP/stdio transports.
+ *
+ * @module direct
+ */
+export type { DirectClient, ConnectOptions, LLMConnectOptions, SessionOptions, ClientInfo, LLMPlatform, SearchSkillsOptions, SearchSkillsResult, SkillSearchResultItem, LoadSkillsOptions, LoadSkillsResult, LoadedSkillItem, ListSkillsOptions, ListSkillsResult, ElicitationRequest, ElicitationResponse, ElicitationHandler, CompleteOptions, CompleteResult, McpLogLevel, } from './client.types';
+export { connect, connectOpenAI, connectClaude, connectLangChain, connectVercelAI } from './connect';
+export { DirectClientImpl } from './direct-client';
+export { detectPlatform, formatToolsForPlatform, formatResultForPlatform, PLATFORM_CLIENT_INFO } from './llm-platform';
+export type { OpenAITool, ClaudeTool, LangChainTool, VercelAITool, VercelAITools } from './llm-platform';
+export type { DirectMcpServer, DirectAuthContext, DirectCallOptions, DirectRequestMetadata } from './direct.types';
+export { DirectMcpServerImpl } from './direct-server';
+//# sourceMappingURL=index.d.ts.map

package/direct/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/direct/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,WAAW,EAEX,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAEhB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAElB,eAAe,EACf,cAAc,EAEd,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAMrG,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACvH,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMzG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEnH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/direct/llm-platform.d.ts

@@ -0,0 +1,94 @@
+/**
+ * LLM Platform Detection and Formatting
+ *
+ * Detects LLM platform from clientInfo and formats tools/results accordingly.
+ */
+import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { LLMPlatform, ClientInfo } from './client.types';
+/**
+ * Client info presets for each LLM platform.
+ * Used by LLM-specific connect helpers.
+ */
+export declare const PLATFORM_CLIENT_INFO: Record<LLMPlatform, ClientInfo>;
+/**
+ * Detect LLM platform from clientInfo.
+ *
+ * @param clientInfo - MCP client info from handshake
+ * @returns Detected LLM platform
+ *
+ * @example
+ * ```typescript
+ * detectPlatform({ name: 'openai-agent', version: '1.0.0' }); // 'openai'
+ * detectPlatform({ name: 'claude', version: '1.0.0' }); // 'claude'
+ * detectPlatform({ name: 'my-agent', version: '1.0.0' }); // 'raw'
+ * ```
+ */
+export declare function detectPlatform(clientInfo: ClientInfo): LLMPlatform;
+/** OpenAI function calling tool format */
+export interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+        strict: boolean;
+    };
+}
+/** Anthropic Claude tool format */
+export interface ClaudeTool {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/** LangChain tool schema format */
+export interface LangChainTool {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+}
+/** Vercel AI SDK tool format */
+export interface VercelAITool {
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** Vercel AI tools map */
+export type VercelAITools = Record<string, VercelAITool>;
+/**
+ * Union of all platform-specific tool formats.
+ * Returned by formatToolsForPlatform based on detected platform.
+ */
+export type FormattedTools = OpenAITool[] | ClaudeTool[] | LangChainTool[] | VercelAITools | McpTool[];
+/**
+ * Union of all platform-specific tool result formats.
+ * Returned by formatResultForPlatform based on detected platform.
+ */
+export type FormattedToolResult = string | unknown | Array<{
+    type: string;
+    text: string;
+}> | CallToolResult | {
+    text?: string[];
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+};
+/**
+ * Format MCP tools for the specified LLM platform.
+ *
+ * @param tools - MCP tools from listTools()
+ * @param platform - Target LLM platform
+ * @returns Tools formatted for the platform
+ */
+export declare function formatToolsForPlatform(tools: McpTool[], platform: LLMPlatform): FormattedTools;
+/**
+ * Format MCP CallToolResult for the specified LLM platform.
+ *
+ * Handles both content-based responses (standard CallToolResult) and
+ * toolResult-based responses (newer MCP SDK versions).
+ *
+ * @param result - MCP tool result from callTool()
+ * @param platform - Target LLM platform
+ * @returns Result formatted for the platform
+ */
+export declare function formatResultForPlatform(result: CallToolResult, platform: LLMPlatform): FormattedToolResult;
+//# sourceMappingURL=llm-platform.d.ts.map

package/direct/llm-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-platform.d.ts","sourceRoot":"","sources":["../../src/direct/llm-platform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,cAAc,EAA6B,MAAM,oCAAoC,CAAC;AACrH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,WAAW,EAAE,UAAU,CAMhE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,CAiBlE;AAMD,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAMD,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAMD,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAMD,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAMzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,EAAE,GAAG,UAAU,EAAE,GAAG,aAAa,EAAE,GAAG,aAAa,GAAG,OAAO,EAAE,CAAC;AAEvG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,OAAO,GACP,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACrC,cAAc,GACd;IACE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD,CAAC;AA0DN;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,GAAG,cAAc,CA+C9F;AA6ED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,GAAG,mBAAmB,CAuC1G"}

package/elicitation/elicitation-fallback.schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Elicitation Fallback JSON Schema
+ *
+ * Defines the JSON Schema for elicitation fallback responses.
+ * This schema is used to extend tool output schemas when elicitation is enabled,
+ * allowing tools to return either their normal output OR an elicitation pending response.
+ *
+ * The fallback response instructs the LLM to collect user input and call
+ * sendElicitationResult to continue the original tool execution.
+ */
+/**
+ * JSON Schema for the elicitation fallback response type.
+ * This is used in oneOf union with tool output schemas.
+ */
+export declare const ELICITATION_FALLBACK_JSON_SCHEMA: Record<string, unknown>;
+/**
+ * Type representing the elicitation fallback response structure.
+ * Used for type-checking at compile time.
+ */
+export interface ElicitationFallbackResponse {
+    elicitationPending: {
+        /** Unique identifier for this elicitation request */
+        elicitId: string;
+        /** Question or prompt to display to the user */
+        message: string;
+        /** Instructions for the LLM on handling the request */
+        instructions?: string;
+        /** JSON Schema for expected response */
+        schema?: Record<string, unknown>;
+    };
+}
+//# sourceMappingURL=elicitation-fallback.schema.d.ts.map

package/elicitation/elicitation-fallback.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation-fallback.schema.d.ts","sourceRoot":"","sources":["../../src/elicitation/elicitation-fallback.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CA6BpE,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,kBAAkB,EAAE;QAClB,qDAAqD;QACrD,QAAQ,EAAE,MAAM,CAAC;QACjB,gDAAgD;QAChD,OAAO,EAAE,MAAM,CAAC;QAChB,uDAAuD;QACvD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,wCAAwC;QACxC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;CACH"}

package/elicitation/elicitation.types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Elicitation Types - MCP Elicitation Support
+ *
+ * Types for requesting interactive user input from MCP clients during
+ * tool or agent execution.
+ */
+import { ZodType } from 'zod';
+import { Infer } from '../types/zod.types';
+/**
+ * Default timeout for elicitation requests (5 minutes).
+ */
+export declare const DEFAULT_ELICIT_TTL = 300000;
+/**
+ * Possible statuses for an elicitation result.
+ *
+ * - `accept`: User submitted/accepted the elicitation (MCP SDK calls this 'accept')
+ * - `cancel`: User cancelled the elicitation
+ * - `decline`: User declined to provide information
+ */
+export type ElicitStatus = 'accept' | 'cancel' | 'decline';
+/**
+ * Result of an elicitation request.
+ *
+ * @template T - The type of the content when status is 'accept'
+ */
+export interface ElicitResult<T = unknown> {
+    /**
+     * The user's action in response to the elicitation.
+     * Valid values: 'accept' | 'cancel' | 'decline' (see ElicitStatus)
+     */
+    status: ElicitStatus;
+    /**
+     * The validated content from the user's response.
+     * Only present when status is 'accept'.
+     */
+    content?: T;
+}
+/**
+ * Elicitation mode.
+ *
+ * - `form`: Display a form to collect structured input (most common)
+ * - `url`: Redirect user to a URL for out-of-band interaction (OAuth, payments)
+ */
+export type ElicitMode = 'form' | 'url';
+/**
+ * Options for elicitation requests.
+ */
+export interface ElicitOptions {
+    /**
+     * The elicitation mode.
+     * @default 'form'
+     */
+    mode?: ElicitMode;
+    /**
+     * Timeout in milliseconds before the elicitation request times out.
+     * On timeout, an ElicitationTimeoutError is thrown to kill execution.
+     * @default 300000 (5 minutes)
+     */
+    ttl?: number;
+    /**
+     * Unique identifier for URL-mode elicitation.
+     * Required for URL mode to track completion via notifications.
+     */
+    elicitationId?: string;
+}
+/**
+ * Typed elicitation result that preserves the schema type.
+ *
+ * @template T - Zod schema type
+ */
+export type TypedElicitResult<T extends ZodType> = ElicitResult<Infer<T>>;
+/**
+ * MCP SDK elicitation result format.
+ *
+ * This represents the raw format from MCP SDK where `action` is used instead of `status`.
+ * Used in transport layer when handling responses from the client.
+ */
+export interface McpElicitResult {
+    /** The user's action (MCP SDK uses 'action' instead of 'status') */
+    action: ElicitStatus;
+    /** The content from the user's response (only present when action is 'accept') */
+    content?: unknown;
+}
+/**
+ * Internal pending elicit tracking structure.
+ * Used by transport adapters to manage pending elicitation requests.
+ */
+export interface PendingElicit<T = unknown> {
+    /** Unique identifier for this elicit request */
+    elicitId: string;
+    /** Handle for the timeout timer */
+    timeoutHandle: ReturnType<typeof setTimeout>;
+    /** Resolve function to complete the elicit promise */
+    resolve: (result: ElicitResult<T>) => void;
+    /** Reject function to fail the elicit promise */
+    reject: (err: unknown) => void;
+}
+/**
+ * Pending elicitation fallback record.
+ *
+ * Stores context needed to re-invoke the tool when the result arrives
+ * via the sendElicitationResult tool. Used for clients that don't support
+ * the standard MCP elicitation protocol.
+ */
+export interface PendingElicitFallback {
+    /** Unique identifier for this elicit request */
+    elicitId: string;
+    /** Session ID that initiated the elicitation */
+    sessionId: string;
+    /** Name of the tool that requested elicitation */
+    toolName: string;
+    /** Original input arguments passed to the tool */
+    toolInput: unknown;
+    /** Message displayed to the user */
+    elicitMessage: string;
+    /** JSON Schema for the expected response */
+    elicitSchema: Record<string, unknown>;
+    /** Timestamp when the elicitation was created */
+    createdAt: number;
+    /** Absolute timestamp when the elicitation expires */
+    expiresAt: number;
+}
+/**
+ * Pre-resolved elicit result for fallback continuation.
+ *
+ * Stored when sendElicitationResult is called, and retrieved when
+ * the tool is re-invoked to provide the elicit result immediately.
+ */
+export interface ResolvedElicitResult {
+    /** Unique identifier for this elicit request */
+    elicitId: string;
+    /** The elicitation result from the user */
+    result: ElicitResult<unknown>;
+    /** Timestamp when the result was resolved */
+    resolvedAt: number;
+}
+/**
+ * Result of fallback execution from sendElicitationResult.
+ *
+ * Published via pub/sub to notify the original waiting request
+ * when the tool re-invocation completes.
+ */
+export interface FallbackExecutionResult {
+    /** Whether the tool execution succeeded */
+    success: boolean;
+    /** The tool result when success is true (MCP CallToolResult) */
+    result?: unknown;
+    /** Error message when success is false */
+    error?: string;
+}
+/**
+ * Callback type for fallback result subscriptions.
+ */
+export type FallbackResultCallback = (result: FallbackExecutionResult) => void;
+/**
+ * Default timeout for waiting fallback requests (5 minutes).
+ * Should match DEFAULT_ELICIT_TTL.
+ */
+export declare const DEFAULT_FALLBACK_WAIT_TTL = 300000;
+//# sourceMappingURL=elicitation.types.d.ts.map

package/elicitation/elicitation.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation.types.d.ts","sourceRoot":"","sources":["../../src/elicitation/elicitation.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,EAAE,YAAY,CAAC;IAErB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IAEjB,mCAAmC;IACnC,aAAa,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE7C,sDAAsD;IACtD,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE3C,iDAAiD;IACjD,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IAEjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IAEnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IAEtB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAElB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAE9B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IAEjB,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,yBAAyB,SAAS,CAAC"}

package/elicitation/flows/elicitation-request.flow.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Elicitation Request Flow
+ *
+ * Flow for initiating an elicitation request to the client.
+ * Provides hook points for middleware/plugins to intercept elicitation.
+ *
+ * @module elicitation/flows/elicitation-request.flow
+ */
+import { FlowBase, FlowRunOptions } from '../../common';
+import { z } from 'zod';
+import type { PendingElicitRecord } from '../store';
+declare const inputSchema: z.ZodObject<{
+    relatedRequestId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    sessionId: z.ZodString;
+    message: z.ZodString;
+    requestedSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    options: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            url: "url";
+            form: "form";
+        }>>;
+        ttl: z.ZodOptional<z.ZodNumber>;
+        elicitationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodObject<{
+    elicitId: z.ZodString;
+    sessionId: z.ZodString;
+    expiresAt: z.ZodNumber;
+    mode: z.ZodEnum<{
+        url: "url";
+        form: "form";
+    }>;
+    requestParams: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    pendingRecord: z.ZodType<PendingElicitRecord>;
+}, z.core.$strip>;
+declare const stateSchema: z.ZodObject<{
+    relatedRequestId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    sessionId: z.ZodString;
+    message: z.ZodString;
+    requestedSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        url: "url";
+        form: "form";
+    }>>;
+    ttl: z.ZodDefault<z.ZodNumber>;
+    elicitationId: z.ZodOptional<z.ZodString>;
+    elicitId: z.ZodString;
+    expiresAt: z.ZodNumber;
+    pendingRecord: z.ZodType<PendingElicitRecord | undefined>;
+    requestParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    output: z.ZodOptional<z.ZodObject<{
+        elicitId: z.ZodString;
+        sessionId: z.ZodString;
+        expiresAt: z.ZodNumber;
+        mode: z.ZodEnum<{
+            url: "url";
+            form: "form";
+        }>;
+        requestParams: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        pendingRecord: z.ZodType<PendingElicitRecord>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const plan: {
+    readonly pre: ["parseInput", "validateRequest"];
+    readonly execute: ["generateElicitId", "storePendingRecord", "buildRequestParams"];
+    readonly finalize: ["finalize"];
+};
+declare global {
+    interface ExtendFlows {
+        'elicitation:request': FlowRunOptions<ElicitationRequestFlow, typeof plan, typeof inputSchema, typeof outputSchema, typeof stateSchema>;
+    }
+}
+declare const name: "elicitation:request";
+/**
+ * Flow for preparing an elicitation request.
+ *
+ * This flow handles the preparation stages of an elicitation:
+ * 1. Parse and validate input
+ * 2. Validate the request (mode requirements)
+ * 3. Generate elicit ID
+ * 4. Store pending record
+ * 5. Build request parameters
+ *
+ * The actual sending and waiting for response is handled by the transport
+ * adapter after this flow completes.
+ */
+export default class ElicitationRequestFlow extends FlowBase<typeof name> {
+    logger: import("../../common").FrontMcpLogger;
+    parseInput(): Promise<void>;
+    validateRequest(): Promise<void>;
+    generateElicitId(): Promise<void>;
+    storePendingRecord(): Promise<void>;
+    buildRequestParams(): Promise<void>;
+    finalize(): Promise<void>;
+}
+export { ElicitationRequestFlow };
+//# sourceMappingURL=elicitation-request.flow.d.ts.map

package/elicitation/flows/elicitation-request.flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation-request.flow.d.ts","sourceRoot":"","sources":["../../../src/elicitation/flows/elicitation-request.flow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAyB,cAAc,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAGpD,QAAA,MAAM,WAAW;;;;;;;;;;;;;iBAiBf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;;;mBAYU,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;iBACxD,CAAC;AAEH,QAAA,MAAM,WAAW;;;;;;;;;;;;;mBAUsB,CAAC,CAAC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;;;;;;;;;;;uBAbrD,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;;iBAgBxD,CAAC;AAEH,QAAA,MAAM,IAAI;;;;CAI2B,CAAC;AAEtC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,WAAW;QACnB,qBAAqB,EAAE,cAAc,CACnC,sBAAsB,EACtB,OAAO,IAAI,EACX,OAAO,WAAW,EAClB,OAAO,YAAY,EACnB,OAAO,WAAW,CACnB,CAAC;KACH;CACF;AAED,QAAA,MAAM,IAAI,EAAG,qBAA8B,CAAC;AAG5C;;;;;;;;;;;;GAYG;AAQH,MAAM,CAAC,OAAO,OAAO,sBAAuB,SAAQ,QAAQ,CAAC,OAAO,IAAI,CAAC;IACvE,MAAM,wCAAoD;IAGpD,UAAU;IAoBV,eAAe;IAcf,gBAAgB;IAehB,kBAAkB;IAuBlB,kBAAkB;IAyBlB,QAAQ;CAuBf;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}