@web-interact-mcp/client
Version:
A production-ready TypeScript library that transforms web applications into MCP (Model Context Protocol) servers with robust two-way communication via SignalR
408 lines • 14.5 kB
TypeScript
/**
* @fileoverview Web Interact MCP Controller - Production-ready controller for MCP tool execution and management
* @description Enterprise-grade controller that transforms web applications into MCP servers with robust tool execution
* @version 1.0.0
* @author Vijay Nirmal
*/
import { ToolConfiguration, ToolStartConfig, CallToolResult, WebInteractMCPOptions, WebInteractMCPEvent, CustomFunction, ReturnValueProviderFunction, VisualEffectStyles, ToolParameterSchema, ILogger } from './types';
import { ToolRegistry } from './tool-registry';
/**
* Production-ready controller class for Web Interact MCP
* Provides comprehensive tool execution, registration, and management capabilities
* with enterprise-grade logging, error handling, and monitoring
*/
export declare class WebInteractMCPController {
private readonly registry;
private readonly logger;
private shepherdTour;
private activeTool;
private toolQueue;
private currentStepIndex;
private readonly eventListeners;
private globalOptions;
private readonly shepherdOptions;
private readonly customFunctions;
private readonly returnValueProviders;
private stepReturnValues;
private customStyles;
private readonly styleElementId;
private signalRService;
/**
* Creates a new production-ready WebInteractMCPController instance
* @param options - Global configuration options
* @param shepherdOptions - Optional Shepherd.js tour configuration (uses production defaults if not provided)
* @param logger - Optional custom logger implementation (uses ConsoleLogger if not provided)
*/
constructor(options?: Partial<WebInteractMCPOptions>, shepherdOptions?: any, logger?: ILogger);
/**
* Gets the tool registry instance for managing tool configurations
* @returns The tool registry instance
*/
getRegistry(): ToolRegistry;
/**
* Gets the current global configuration options
* @returns A copy of the current global options
*/
getGlobalOptions(): WebInteractMCPOptions;
/**
* Gets the current logger instance
* @returns The logger instance
*/
getLogger(): ILogger;
/**
* Updates global configuration options
* @param options - Partial options to update
*/
updateGlobalOptions(options: Partial<WebInteractMCPOptions>): void;
/**
* Updates the visual effect styles and regenerates the CSS
* @param styles - Partial visual effect styles to update
*/
updateVisualEffectStyles(styles: Partial<VisualEffectStyles>): void;
/**
* Gets the current visual effect styles.
* @returns The current visual effect styles.
*/
getVisualEffectStyles(): VisualEffectStyles;
/**
* Resets visual effect styles to default values
*/
resetVisualEffectStyles(): void;
/**
* Sets a specific style property for a visual effect
* @param effect - The visual effect to modify
* @param property - The property to set
* @param value - The value to set
*/
setVisualEffectProperty(effect: keyof VisualEffectStyles, property: string, value: any): void;
/**
* Registers a custom function that can be called from tool steps
* @param customFunction - The custom function configuration
*/
registerCustomFunction(customFunction: CustomFunction): void;
/**
* Registers multiple custom functions
* @param functions - Array of custom function configurations
*/
registerCustomFunctions(functions: CustomFunction[]): void;
/**
* Unregisters a custom function
* @param functionName - The name of the function to unregister
*/
unregisterCustomFunction(functionName: string): void;
/**
* Gets a registered custom function.
* @param functionName - The name of the function to retrieve.
* @returns The custom function configuration or undefined if not found.
*/
getCustomFunction(functionName: string): CustomFunction | undefined; /**
* Gets all registered custom functions.
* @returns Map of all registered custom functions.
*/
getAllCustomFunctions(): Map<string, CustomFunction>;
/**
* Registers a return value provider function that can be called from tool steps
* @param provider - The return value provider configuration
*/
registerReturnValueProvider(provider: ReturnValueProviderFunction): void;
/**
* Registers multiple return value provider functions
* @param providers - Array of return value provider configurations
*/
registerReturnValueProviders(providers: ReturnValueProviderFunction[]): void;
/**
* Unregisters a return value provider function
* @param providerName - The name of the provider to unregister
*/
unregisterReturnValueProvider(providerName: string): void;
/**
* Gets a registered return value provider function.
* @param providerName - The name of the provider to retrieve.
* @returns The return value provider configuration or undefined if not found.
*/
getReturnValueProvider(providerName: string): ReturnValueProviderFunction | undefined;
/**
* Gets all registered return value provider functions.
* @returns Map of all registered return value providers.
*/
getAllReturnValueProviders(): Map<string, ReturnValueProviderFunction>;
/**
* Gets the effective options for a tool (merges global and tool-specific options)
* @private
* @param tool - The tool configuration
* @returns The effective options for the tool
*/
private getEffectiveOptions;
/**
* Starts a sequence of Tools.
* @param toolsToStart - An array of objects, each with a toolId and optional parameters to pass to the tool.
* @returns Promise that resolves with an array of CallToolResult from each tool execution.
*/
start(toolsToStart: ToolStartConfig[]): Promise<CallToolResult[]>;
/**
* Stops the currently active tool and clears the queue.
*/
stop(): void;
/**
* Manually advances to the next step (for 'normal' mode).
*/
next(): void;
/**
* Manually goes back to the previous step (for 'normal' mode).
*/
back(): void;
/**
* Registers an event listener for tool events.
* @param eventName - The name of the event.
* @param handler - The callback function.
*/
on(eventName: WebInteractMCPEvent, handler: Function): void;
/**
* Removes an event listener.
* @param eventName - The name of the event.
* @param handler - The callback function to remove.
*/
off(eventName: WebInteractMCPEvent, handler: Function): void;
/**
* Emits an event to all registered listeners.
* @private
* @param eventName - The name of the event to emit.
* @param data - Optional data to pass to the event handlers.
*/
private emit;
/**
* Executes the next tool in the queue.
* @private
*/
private executeNextTool;
/**
* Executes a single tool.
* @private
* @param toolId - The ID of the tool to execute.
* @param params - Optional parameters to pass to the tool.
* @returns Promise that resolves with the tool execution result.
*/
private executeTool;
/**
* Executes a tool in normal mode (with buttons).
* @private
*/
private executeNormalMode;
/**
* Executes a tool in buttonless mode (auto-advancing).
* @private
*/
private executeButtonlessMode;
/**
* Executes a tool in silent mode (no UI, automated actions).
* @private
*/
private executeSilentMode;
/**
* Calculates the return value for a step based on its configuration.
* @private
* @param step - The step configuration.
* @param toolParams - Tool-level parameters.
* @param stepIndex - The current step index.
* @returns The calculated return value.
*/
private calculateStepReturnValue;
/**
* Calculates the tool-level return value based on the tool configuration.
* @private
* @param tool - The tool configuration.
* @param toolParams - Tool-level parameters.
* @param stepsExecuted - Number of steps executed.
* @param toolExecutionSuccess - Whether the tool executed successfully.
* @param toolExecutionError - Any error that occurred during tool execution.
* @returns The calculated tool-level return value.
*/
private calculateToolReturnValue;
/**
* Prepares steps by substituting parameters.
* @private
*/
private prepareSteps;
/**
* Substitutes parameters in a string or value.
* @private
*/
private substituteParams;
/**
* Creates buttons for a step in normal mode.
* @private
*/
private createStepButtons;
/**
* Sets up event handlers for the Shepherd tour with return value support.
* @private
*/
private setupTourEventHandlersWithReturnValues;
/**
* Performs an automated action on a DOM element.
* @private
* @returns The result of the action as a CallToolResult.
*/
private performAction;
/**
* Wait for an element to be available in the DOM
* @private
*/
private waitForElement;
/**
* Executes a custom function as part of a tool action.
* @private
* @returns The return value from the custom function.
*/
private executeCustomFunction;
/**
* Initializes default event listeners.
* @private
*/
private initializeEventListeners;
/**
* Injects CSS styles for visual feedback animations.
* @private
*/
private injectVisualFeedbackStyles; /**
* Shows a click visual effect on an element.
* @private
*/
private showClickEffect;
/**
* Shows typing animation on an input element.
* @private
*/
private showTypingEffect; /**
* Highlights an element temporarily.
* @private
*/
private highlightElement; /**
* Shows a focus effect on an element.
* @private
*/
private showFocusEffect;
/**
* Sets whether visual feedback is enabled.
*/
setVisualFeedbackEnabled(enabled: boolean): void;
/**
* Gets whether visual feedback is enabled.
*/
isVisualFeedbackEnabled(): boolean;
/**
* Applies a predefined theme to the visual effects.
* @param theme - The theme name to apply.
*/
applyVisualEffectTheme(theme: 'default' | 'dark' | 'success' | 'warning' | 'error' | 'custom'): void;
/**
* Gets a list of available predefined themes.
* @returns Array of available theme names.
*/
getAvailableThemes(): string[];
/**
* Gets the parameter schema for a specific tool.
* @param toolId - The ID of the tool.
* @returns The parameter schema or undefined if the tool doesn't exist or has no schema.
*/
getToolParameterSchema(toolId: string): ToolParameterSchema | undefined;
/**
* Validates parameters against a tool's parameter schema.
* @param toolId - The ID of the tool.
* @param params - The parameters to validate.
* @returns Validation result with success flag and error messages.
*/
validateToolParameters(toolId: string, params: Record<string, any>): {
isValid: boolean;
errors: string[];
warnings: string[];
};
/**
* Validates a single parameter value against its definition.
* @private
* @param paramName - The name of the parameter.
* @param value - The value to validate.
* @param definition - The parameter definition.
* @returns Validation result.
*/
private validateParameterValue;
/**
* Gets all available tools with their parameter schemas for MCP server discovery.
* @returns Map of tool configurations with parameter schemas.
*/
getToolsWithParameterSchemas(): Map<string, {
tool: ToolConfiguration;
hasParameters: boolean;
}>;
/**
* Applies default values to parameters based on the tool's parameter schema.
* @param toolId - The ID of the tool.
* @param params - The input parameters.
* @returns Parameters with default values applied.
*/
applyParameterDefaults(toolId: string, params: Record<string, any>): Record<string, any>;
/**
* Gets the return values from the last executed tool.
* @returns Array of return values from each step of the last tool.
*/
getLastToolReturnValues(): CallToolResult[];
/**
* Gets the return value from the last step of the last executed tool.
* @returns The return value from the last step, or undefined if no steps were executed.
*/
getLastStepReturnValue(): CallToolResult | undefined;
/**
* Creates a new session with the MCP Server via SignalR.
* @returns Promise that resolves with the session ID
*/
createSession(): Promise<string>;
/**
* Closes the current session and stops the SignalR connection.
*/
closeSession(): Promise<void>;
/**
* Gets the current session ID.
* @returns The current session ID or null if no session is active.
*/
getCurrentSessionId(): string | null;
/**
* Checks if a session is currently active.
* @returns True if a session is active, false otherwise.
*/
isSessionActive(): boolean;
/**
* Gets the SignalR connection status.
* @returns Object containing connection status information.
*/
getConnectionStatus(): {
isConnected: boolean;
connectionState: string | null;
sessionId: string | null;
};
/**
* Performs cleanup operations for graceful shutdown
* @returns Promise that resolves when cleanup is complete
*/
dispose(): Promise<void>;
/**
* Gets comprehensive statistics about the controller state
* @returns Controller statistics
*/
getStatistics(): {
tools: {
total: number;
withParameterSchemas: number;
byMode: Record<string, number>;
};
customFunctions: number;
returnValueProviders: number;
eventListeners: Record<string, number>;
execution: {
currentlyActive: boolean;
activeTool: string | null;
queuedTools: number;
lastExecutionResults: number;
};
};
}
//# sourceMappingURL=controller.d.ts.map