@leanmcp/elicitation 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,345 @@
+/**
+ * Elicitation request structure following MCP spec
+ */
+interface ElicitationRequest {
+    type: 'elicitation';
+    title: string;
+    description?: string;
+    fields: ElicitationField[];
+    metadata?: {
+        stepNumber?: number;
+        totalSteps?: number;
+        previousValues?: Record<string, any>;
+        [key: string]: any;
+    };
+}
+/**
+ * Individual field in elicitation form
+ */
+interface ElicitationField {
+    name: string;
+    label: string;
+    type: 'text' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'email' | 'url' | 'textarea';
+    description?: string;
+    required?: boolean;
+    defaultValue?: any;
+    options?: Array<{
+        label: string;
+        value: any;
+    }>;
+    validation?: FieldValidation;
+    placeholder?: string;
+    helpText?: string;
+}
+/**
+ * Field validation rules
+ */
+interface FieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    customValidator?: (value: any) => boolean | string;
+    errorMessage?: string;
+}
+/**
+ * Elicitation response from user
+ */
+interface ElicitationResponse {
+    values: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+/**
+ * Strategy configuration
+ */
+interface ElicitationStrategyConfig {
+    strategy: 'form' | 'conversational' | 'multi-step';
+    onComplete?: (values: Record<string, any>) => void;
+    onValidationError?: (errors: ValidationError[]) => void;
+}
+/**
+ * Validation error
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Elicitation configuration for decorator
+ */
+interface ElicitationConfig {
+    strategy?: 'form' | 'conversational' | 'multi-step';
+    title?: string;
+    description?: string;
+    fields?: ElicitationField[];
+    condition?: (args: any) => boolean;
+    builder?: (context: ElicitationContext) => ElicitationRequest | ElicitationStep[];
+}
+/**
+ * Context passed to elicitation builder
+ */
+interface ElicitationContext {
+    args: any;
+    meta?: any;
+    previousAttempts?: number;
+}
+/**
+ * Multi-step elicitation step
+ */
+interface ElicitationStep {
+    title: string;
+    description?: string;
+    fields: ElicitationField[];
+    condition?: (previousValues: Record<string, any>) => boolean;
+}
+/**
+ * Elicitation error
+ */
+declare class ElicitationError extends Error {
+    code: string;
+    details?: any | undefined;
+    constructor(message: string, code: string, details?: any | undefined);
+}
+
+/**
+ * Check if method arguments are missing required fields
+ */
+declare function checkMissingFields(args: any, config: ElicitationConfig): boolean;
+/**
+ * Decorator to mark a method as requiring elicitation
+ *
+ * @example
+ * // Simple form elicitation
+ * @Tool({ description: 'Create Slack channel' })
+ * @Elicitation({
+ *   title: 'Create Channel',
+ *   fields: [
+ *     { name: 'channelName', label: 'Channel Name', type: 'text', required: true },
+ *     { name: 'isPrivate', label: 'Private Channel', type: 'boolean', defaultValue: false }
+ *   ]
+ * })
+ * async createChannel(args: CreateChannelInput) {
+ *   // Method receives complete args after elicitation
+ * }
+ *
+ * @example
+ * // Conditional elicitation
+ * @Tool({ description: 'Send message' })
+ * @Elicitation({
+ *   condition: (args) => !args.channelId,
+ *   title: 'Select Channel',
+ *   fields: [
+ *     { name: 'channelId', label: 'Channel', type: 'select', required: true }
+ *   ]
+ * })
+ * async sendMessage(args: SendMessageInput) {
+ *   // Only elicits if channelId is missing
+ * }
+ *
+ * @example
+ * // Multi-step elicitation
+ * @Tool({ description: 'Deploy app' })
+ * @Elicitation({
+ *   strategy: 'multi-step',
+ *   builder: () => [
+ *     {
+ *       title: 'Step 1: Environment',
+ *       fields: [{ name: 'env', label: 'Environment', type: 'select', required: true }]
+ *     },
+ *     {
+ *       title: 'Step 2: Config',
+ *       fields: [{ name: 'replicas', label: 'Replicas', type: 'number', defaultValue: 3 }]
+ *     }
+ *   ]
+ * })
+ * async deployApp(args: DeployConfig) {
+ *   // Implementation
+ * }
+ */
+declare function Elicitation(config: ElicitationConfig): MethodDecorator;
+/**
+ * Check if a method requires elicitation
+ */
+declare function isElicitationEnabled(method: Function): boolean;
+/**
+ * Get elicitation configuration for a method
+ */
+declare function getElicitationConfig(method: Function): ElicitationConfig | undefined;
+/**
+ * Get elicitation strategy type for a method
+ */
+declare function getElicitationStrategy(method: Function): string | undefined;
+/**
+ * Build elicitation request from method metadata
+ */
+declare function buildElicitationRequest(method: Function, args: any, meta?: any): ElicitationRequest | null;
+
+/**
+ * Base class for elicitation strategies
+ * Extend this class to implement custom elicitation strategies
+ */
+declare abstract class ElicitationStrategyBase {
+    /**
+     * Build an elicitation request from configuration and context
+     */
+    abstract buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+    /**
+     * Validate user response against field definitions
+     */
+    validateResponse(response: ElicitationResponse, fields: ElicitationField[]): ValidationError[];
+    /**
+     * Validate field type
+     */
+    protected validateFieldType(value: any, field: ElicitationField): ValidationError | null;
+    /**
+     * Validate field against validation rules
+     */
+    protected validateField(value: any, field: ElicitationField): ValidationError | null;
+    /**
+     * Merge elicited values with original arguments
+     */
+    mergeWithArgs(originalArgs: any, elicitedValues: Record<string, any>): any;
+}
+
+/**
+ * Form-based elicitation strategy
+ * Presents all fields at once in a single form
+ */
+declare class FormElicitationStrategy extends ElicitationStrategyBase {
+    buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+}
+
+/**
+ * Multi-step elicitation strategy
+ * Breaks elicitation into multiple sequential steps
+ */
+declare class MultiStepElicitationStrategy extends ElicitationStrategyBase {
+    private steps;
+    private currentStep;
+    private accumulatedValues;
+    constructor(steps: ElicitationStep[]);
+    buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+    /**
+     * Check if there are more steps
+     */
+    hasNextStep(): boolean;
+    /**
+     * Move to next step and accumulate values
+     */
+    nextStep(values: Record<string, any>): void;
+    /**
+     * Get all accumulated values
+     */
+    getAccumulatedValues(): Record<string, any>;
+    /**
+     * Reset to first step
+     */
+    reset(): void;
+    /**
+     * Override merge to include all accumulated values
+     */
+    mergeWithArgs(originalArgs: any, elicitedValues: Record<string, any>): any;
+}
+
+/**
+ * Fluent builder for creating elicitation forms
+ *
+ * @example
+ * const config = new ElicitationFormBuilder()
+ *   .title('Create Slack Channel')
+ *   .description('Please provide channel details')
+ *   .addTextField('channelName', 'Channel Name', { required: true })
+ *   .addBooleanField('isPrivate', 'Private Channel', { defaultValue: false })
+ *   .addSelectField('team', 'Team', [
+ *     { label: 'Engineering', value: 'eng' },
+ *     { label: 'Marketing', value: 'mkt' }
+ *   ])
+ *   .build();
+ */
+declare class ElicitationFormBuilder {
+    private fields;
+    private config;
+    /**
+     * Set the form title
+     */
+    title(title: string): this;
+    /**
+     * Set the form description
+     */
+    description(description: string): this;
+    /**
+     * Set a condition for when elicitation should occur
+     */
+    condition(condition: (args: any) => boolean): this;
+    /**
+     * Add a text field
+     */
+    addTextField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a textarea field
+     */
+    addTextAreaField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a number field
+     */
+    addNumberField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a boolean field (checkbox)
+     */
+    addBooleanField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a select field (dropdown)
+     */
+    addSelectField(name: string, label: string, options: Array<{
+        label: string;
+        value: any;
+    }>, fieldOptions?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type' | 'options'>>): this;
+    /**
+     * Add a multi-select field
+     */
+    addMultiSelectField(name: string, label: string, options: Array<{
+        label: string;
+        value: any;
+    }>, fieldOptions?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type' | 'options'>>): this;
+    /**
+     * Add an email field
+     */
+    addEmailField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a URL field
+     */
+    addUrlField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a date field
+     */
+    addDateField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a custom field with full control
+     */
+    addCustomField(field: ElicitationField): this;
+    /**
+     * Build the final configuration
+     */
+    build(): ElicitationConfig;
+}
+/**
+ * Helper function to create validation rules
+ */
+declare class ValidationBuilder {
+    private validation;
+    min(min: number): this;
+    max(max: number): this;
+    minLength(minLength: number): this;
+    maxLength(maxLength: number): this;
+    pattern(pattern: string): this;
+    customValidator(validator: (value: any) => boolean | string): this;
+    errorMessage(message: string): this;
+    build(): FieldValidation;
+}
+/**
+ * Helper to create validation rules
+ */
+declare function validation(): ValidationBuilder;
+
+export { Elicitation, type ElicitationConfig, type ElicitationContext, ElicitationError, type ElicitationField, ElicitationFormBuilder, type ElicitationRequest, type ElicitationResponse, type ElicitationStep, ElicitationStrategyBase, type ElicitationStrategyConfig, type FieldValidation, FormElicitationStrategy, MultiStepElicitationStrategy, ValidationBuilder, type ValidationError, buildElicitationRequest, checkMissingFields, getElicitationConfig, getElicitationStrategy, isElicitationEnabled, validation };

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Elicitation request structure following MCP spec
+ */
+interface ElicitationRequest {
+    type: 'elicitation';
+    title: string;
+    description?: string;
+    fields: ElicitationField[];
+    metadata?: {
+        stepNumber?: number;
+        totalSteps?: number;
+        previousValues?: Record<string, any>;
+        [key: string]: any;
+    };
+}
+/**
+ * Individual field in elicitation form
+ */
+interface ElicitationField {
+    name: string;
+    label: string;
+    type: 'text' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'email' | 'url' | 'textarea';
+    description?: string;
+    required?: boolean;
+    defaultValue?: any;
+    options?: Array<{
+        label: string;
+        value: any;
+    }>;
+    validation?: FieldValidation;
+    placeholder?: string;
+    helpText?: string;
+}
+/**
+ * Field validation rules
+ */
+interface FieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    customValidator?: (value: any) => boolean | string;
+    errorMessage?: string;
+}
+/**
+ * Elicitation response from user
+ */
+interface ElicitationResponse {
+    values: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+/**
+ * Strategy configuration
+ */
+interface ElicitationStrategyConfig {
+    strategy: 'form' | 'conversational' | 'multi-step';
+    onComplete?: (values: Record<string, any>) => void;
+    onValidationError?: (errors: ValidationError[]) => void;
+}
+/**
+ * Validation error
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Elicitation configuration for decorator
+ */
+interface ElicitationConfig {
+    strategy?: 'form' | 'conversational' | 'multi-step';
+    title?: string;
+    description?: string;
+    fields?: ElicitationField[];
+    condition?: (args: any) => boolean;
+    builder?: (context: ElicitationContext) => ElicitationRequest | ElicitationStep[];
+}
+/**
+ * Context passed to elicitation builder
+ */
+interface ElicitationContext {
+    args: any;
+    meta?: any;
+    previousAttempts?: number;
+}
+/**
+ * Multi-step elicitation step
+ */
+interface ElicitationStep {
+    title: string;
+    description?: string;
+    fields: ElicitationField[];
+    condition?: (previousValues: Record<string, any>) => boolean;
+}
+/**
+ * Elicitation error
+ */
+declare class ElicitationError extends Error {
+    code: string;
+    details?: any | undefined;
+    constructor(message: string, code: string, details?: any | undefined);
+}
+
+/**
+ * Check if method arguments are missing required fields
+ */
+declare function checkMissingFields(args: any, config: ElicitationConfig): boolean;
+/**
+ * Decorator to mark a method as requiring elicitation
+ *
+ * @example
+ * // Simple form elicitation
+ * @Tool({ description: 'Create Slack channel' })
+ * @Elicitation({
+ *   title: 'Create Channel',
+ *   fields: [
+ *     { name: 'channelName', label: 'Channel Name', type: 'text', required: true },
+ *     { name: 'isPrivate', label: 'Private Channel', type: 'boolean', defaultValue: false }
+ *   ]
+ * })
+ * async createChannel(args: CreateChannelInput) {
+ *   // Method receives complete args after elicitation
+ * }
+ *
+ * @example
+ * // Conditional elicitation
+ * @Tool({ description: 'Send message' })
+ * @Elicitation({
+ *   condition: (args) => !args.channelId,
+ *   title: 'Select Channel',
+ *   fields: [
+ *     { name: 'channelId', label: 'Channel', type: 'select', required: true }
+ *   ]
+ * })
+ * async sendMessage(args: SendMessageInput) {
+ *   // Only elicits if channelId is missing
+ * }
+ *
+ * @example
+ * // Multi-step elicitation
+ * @Tool({ description: 'Deploy app' })
+ * @Elicitation({
+ *   strategy: 'multi-step',
+ *   builder: () => [
+ *     {
+ *       title: 'Step 1: Environment',
+ *       fields: [{ name: 'env', label: 'Environment', type: 'select', required: true }]
+ *     },
+ *     {
+ *       title: 'Step 2: Config',
+ *       fields: [{ name: 'replicas', label: 'Replicas', type: 'number', defaultValue: 3 }]
+ *     }
+ *   ]
+ * })
+ * async deployApp(args: DeployConfig) {
+ *   // Implementation
+ * }
+ */
+declare function Elicitation(config: ElicitationConfig): MethodDecorator;
+/**
+ * Check if a method requires elicitation
+ */
+declare function isElicitationEnabled(method: Function): boolean;
+/**
+ * Get elicitation configuration for a method
+ */
+declare function getElicitationConfig(method: Function): ElicitationConfig | undefined;
+/**
+ * Get elicitation strategy type for a method
+ */
+declare function getElicitationStrategy(method: Function): string | undefined;
+/**
+ * Build elicitation request from method metadata
+ */
+declare function buildElicitationRequest(method: Function, args: any, meta?: any): ElicitationRequest | null;
+
+/**
+ * Base class for elicitation strategies
+ * Extend this class to implement custom elicitation strategies
+ */
+declare abstract class ElicitationStrategyBase {
+    /**
+     * Build an elicitation request from configuration and context
+     */
+    abstract buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+    /**
+     * Validate user response against field definitions
+     */
+    validateResponse(response: ElicitationResponse, fields: ElicitationField[]): ValidationError[];
+    /**
+     * Validate field type
+     */
+    protected validateFieldType(value: any, field: ElicitationField): ValidationError | null;
+    /**
+     * Validate field against validation rules
+     */
+    protected validateField(value: any, field: ElicitationField): ValidationError | null;
+    /**
+     * Merge elicited values with original arguments
+     */
+    mergeWithArgs(originalArgs: any, elicitedValues: Record<string, any>): any;
+}
+
+/**
+ * Form-based elicitation strategy
+ * Presents all fields at once in a single form
+ */
+declare class FormElicitationStrategy extends ElicitationStrategyBase {
+    buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+}
+
+/**
+ * Multi-step elicitation strategy
+ * Breaks elicitation into multiple sequential steps
+ */
+declare class MultiStepElicitationStrategy extends ElicitationStrategyBase {
+    private steps;
+    private currentStep;
+    private accumulatedValues;
+    constructor(steps: ElicitationStep[]);
+    buildRequest(config: ElicitationConfig, context: ElicitationContext): ElicitationRequest;
+    /**
+     * Check if there are more steps
+     */
+    hasNextStep(): boolean;
+    /**
+     * Move to next step and accumulate values
+     */
+    nextStep(values: Record<string, any>): void;
+    /**
+     * Get all accumulated values
+     */
+    getAccumulatedValues(): Record<string, any>;
+    /**
+     * Reset to first step
+     */
+    reset(): void;
+    /**
+     * Override merge to include all accumulated values
+     */
+    mergeWithArgs(originalArgs: any, elicitedValues: Record<string, any>): any;
+}
+
+/**
+ * Fluent builder for creating elicitation forms
+ *
+ * @example
+ * const config = new ElicitationFormBuilder()
+ *   .title('Create Slack Channel')
+ *   .description('Please provide channel details')
+ *   .addTextField('channelName', 'Channel Name', { required: true })
+ *   .addBooleanField('isPrivate', 'Private Channel', { defaultValue: false })
+ *   .addSelectField('team', 'Team', [
+ *     { label: 'Engineering', value: 'eng' },
+ *     { label: 'Marketing', value: 'mkt' }
+ *   ])
+ *   .build();
+ */
+declare class ElicitationFormBuilder {
+    private fields;
+    private config;
+    /**
+     * Set the form title
+     */
+    title(title: string): this;
+    /**
+     * Set the form description
+     */
+    description(description: string): this;
+    /**
+     * Set a condition for when elicitation should occur
+     */
+    condition(condition: (args: any) => boolean): this;
+    /**
+     * Add a text field
+     */
+    addTextField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a textarea field
+     */
+    addTextAreaField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a number field
+     */
+    addNumberField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a boolean field (checkbox)
+     */
+    addBooleanField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a select field (dropdown)
+     */
+    addSelectField(name: string, label: string, options: Array<{
+        label: string;
+        value: any;
+    }>, fieldOptions?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type' | 'options'>>): this;
+    /**
+     * Add a multi-select field
+     */
+    addMultiSelectField(name: string, label: string, options: Array<{
+        label: string;
+        value: any;
+    }>, fieldOptions?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type' | 'options'>>): this;
+    /**
+     * Add an email field
+     */
+    addEmailField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a URL field
+     */
+    addUrlField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a date field
+     */
+    addDateField(name: string, label: string, options?: Partial<Omit<ElicitationField, 'name' | 'label' | 'type'>>): this;
+    /**
+     * Add a custom field with full control
+     */
+    addCustomField(field: ElicitationField): this;
+    /**
+     * Build the final configuration
+     */
+    build(): ElicitationConfig;
+}
+/**
+ * Helper function to create validation rules
+ */
+declare class ValidationBuilder {
+    private validation;
+    min(min: number): this;
+    max(max: number): this;
+    minLength(minLength: number): this;
+    maxLength(maxLength: number): this;
+    pattern(pattern: string): this;
+    customValidator(validator: (value: any) => boolean | string): this;
+    errorMessage(message: string): this;
+    build(): FieldValidation;
+}
+/**
+ * Helper to create validation rules
+ */
+declare function validation(): ValidationBuilder;
+
+export { Elicitation, type ElicitationConfig, type ElicitationContext, ElicitationError, type ElicitationField, ElicitationFormBuilder, type ElicitationRequest, type ElicitationResponse, type ElicitationStep, ElicitationStrategyBase, type ElicitationStrategyConfig, type FieldValidation, FormElicitationStrategy, MultiStepElicitationStrategy, ValidationBuilder, type ValidationError, buildElicitationRequest, checkMissingFields, getElicitationConfig, getElicitationStrategy, isElicitationEnabled, validation };