Form Types & Validation

ElicitationField

Defines a single field in an elicitation form.

Field Schema

interface ElicitationField {
  name: string;
  label: string;
  type: FieldType;
  description?: string;
  required?: boolean;
  defaultValue?: any;
  options?: Array<{ label: string; value: any }>;
  validation?: FieldValidation;
  placeholder?: string;
  helpText?: string;
}

name

string

required

Unique field identifier (used as key in response object)

label

string

required

Human-readable field label

type

FieldType

required

Field type (see Field Types below)

description

string

Additional description text

required

boolean

default:"false"

Whether the field is required

defaultValue

any

Default value for the field

options

Array<{label: string, value: any}>

Options for select/multiselect fields

validation

FieldValidation

Validation rules (see Validation below)

placeholder

string

Placeholder text for input fields

helpText

string

Help text displayed below the field

Field Types

text

Single-line text input.

{
  name: 'username',
  label: 'Username',
  type: 'text',
  required: true,
  placeholder: 'Enter username',
  validation: {
    minLength: 3,
    maxLength: 20,
    pattern: '^[a-zA-Z0-9_]+$',
  },
}

textarea

Multi-line text input.

{
  name: 'description',
  label: 'Description',
  type: 'textarea',
  placeholder: 'Enter description',
  helpText: 'Provide a detailed description',
  validation: {
    maxLength: 500,
  },
}

number

Numeric input.

{
  name: 'age',
  label: 'Age',
  type: 'number',
  required: true,
  defaultValue: 18,
  validation: {
    min: 0,
    max: 120,
  },
}

boolean

Checkbox input.

{
  name: 'subscribe',
  label: 'Subscribe to newsletter',
  type: 'boolean',
  defaultValue: false,
}

select

Dropdown selection (single value).

{
  name: 'country',
  label: 'Country',
  type: 'select',
  required: true,
  options: [
    { label: 'United States', value: 'US' },
    { label: 'Canada', value: 'CA' },
    { label: 'United Kingdom', value: 'GB' },
  ],
}

multiselect

Multiple selection.

{
  name: 'interests',
  label: 'Interests',
  type: 'multiselect',
  options: [
    { label: 'Technology', value: 'tech' },
    { label: 'Sports', value: 'sports' },
    { label: 'Music', value: 'music' },
    { label: 'Travel', value: 'travel' },
  ],
}

email

Email input with validation.

{
  name: 'email',
  label: 'Email Address',
  type: 'email',
  required: true,
  placeholder: '[email protected]',
  validation: {
    errorMessage: 'Please enter a valid email address',
  },
}

url

URL input with validation.

{
  name: 'website',
  label: 'Website',
  type: 'url',
  placeholder: 'https://example.com',
  validation: {
    errorMessage: 'Please enter a valid URL',
  },
}

date

Date picker.

{
  name: 'birthdate',
  label: 'Date of Birth',
  type: 'date',
  required: true,
}

FieldValidation

Validation rules for form fields.

interface FieldValidation {
  min?: number;
  max?: number;
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  customValidator?: (value: any) => boolean | string;
  errorMessage?: string;
}

min

number

Minimum value (for number fields)

max

number

Maximum value (for number fields)

minLength

number

Minimum length (for text fields)

maxLength

number

Maximum length (for text fields)

pattern

string

Regular expression pattern

customValidator

(value: any) => boolean | string

Custom validation function. Return true for valid, false or error message string for invalid.

errorMessage

string

Custom error message to display when validation fails

Validation Examples

Text Length Validation

{
  name: 'password',
  label: 'Password',
  type: 'text',
  required: true,
  validation: {
    minLength: 8,
    maxLength: 100,
    errorMessage: 'Password must be between 8-100 characters',
  },
}

Pattern Validation

{
  name: 'phone',
  label: 'Phone Number',
  type: 'text',
  required: true,
  placeholder: '(555) 123-4567',
  validation: {
    pattern: '^\\(\\d{3}\\) \\d{3}-\\d{4}$',
    errorMessage: 'Phone must be in format: (555) 123-4567',
  },
}

Range Validation

{
  name: 'quantity',
  label: 'Quantity',
  type: 'number',
  required: true,
  validation: {
    min: 1,
    max: 100,
    errorMessage: 'Quantity must be between 1 and 100',
  },
}

Custom Validation

{
  name: 'couponCode',
  label: 'Coupon Code',
  type: 'text',
  validation: {
    customValidator: (value) => {
      if (!value) return true; // Optional field
      return value.toUpperCase().startsWith('SAVE') || 'Coupon must start with SAVE';
    },
  },
}

ValidationBuilder

Fluent API for building validation rules.

import { validation } from '@leanmcp/elicitation';

const passwordValidation = validation()
  .minLength(8)
  .maxLength(100)
  .pattern('^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)')
  .errorMessage('Password must contain uppercase, lowercase, and number')
  .build();

Methods

min(value: number)

this

Set minimum value

max(value: number)

this

Set maximum value

minLength(value: number)

this

Set minimum length

maxLength(value: number)

this

Set maximum length

pattern(regex: string)

this

Set regex pattern

customValidator(fn: (value: any) => boolean | string)

this

Add custom validator function

errorMessage(message: string)

this

Set error message

build()

FieldValidation

Build the validation object

Usage Example

import { ElicitationFormBuilder, validation } from '@leanmcp/elicitation';

const form = new ElicitationFormBuilder()
  .title('User Registration')
  .addTextField('username', 'Username', {
    required: true,
    validation: validation()
      .minLength(3)
      .maxLength(20)
      .pattern('^[a-zA-Z0-9_]+$')
      .errorMessage('Username must be 3-20 alphanumeric characters or underscore')
      .build(),
  })
  .addTextField('password', 'Password', {
    required: true,
    validation: validation()
      .minLength(8)
      .customValidator((value) => {
        if (!/[A-Z]/.test(value)) return 'Must contain uppercase letter';
        if (!/[a-z]/.test(value)) return 'Must contain lowercase letter';
        if (!/\d/.test(value)) return 'Must contain number';
        return true;
      })
      .build(),
  })
  .build();

ElicitationFormBuilder

Fluent API for building forms.

Methods

title(title: string)

this

Set form title

description(description: string)

this

Set form description

condition(fn: (args: any) => boolean)

this

Set condition for when elicitation should occur

addTextField(name, label, options?)

this

Add text field

addTextAreaField(name, label, options?)

this

Add textarea field

addNumberField(name, label, options?)

this

Add number field

addBooleanField(name, label, options?)

this

Add boolean field

addSelectField(name, label, options, fieldOptions?)

this

Add select field

addMultiSelectField(name, label, options, fieldOptions?)

this

Add multiselect field

addEmailField(name, label, options?)

this

Add email field

addUrlField(name, label, options?)

this

Add URL field

addDateField(name, label, options?)

this

Add date field

addCustomField(field: ElicitationField)

this

Add custom field with full control

build()

ElicitationConfig

Build the final configuration

Complete Example

import { ElicitationFormBuilder, validation } from '@leanmcp/elicitation';
import { Tool } from '@leanmcp/core';
import { Elicitation } from '@leanmcp/elicitation';

@Tool({ description: 'Create event' })
@Elicitation({
  builder: () => {
    return new ElicitationFormBuilder()
      .title('Create Event')
      .description('Fill out the event details')
      .addTextField('title', 'Event Title', {
        required: true,
        validation: validation().minLength(5).maxLength(100).build(),
      })
      .addTextAreaField('description', 'Description', {
        required: true,
        placeholder: 'Describe your event...',
      })
      .addDateField('date', 'Event Date', {
        required: true,
      })
      .addSelectField('category', 'Category', [
        { label: 'Conference', value: 'conference' },
        { label: 'Workshop', value: 'workshop' },
        { label: 'Webinar', value: 'webinar' },
      ])
      .addNumberField('maxAttendees', 'Max Attendees', {
        defaultValue: 50,
        validation: validation().min(1).max(1000).build(),
      })
      .addBooleanField('requiresRegistration', 'Requires Registration', {
        defaultValue: true,
      })
      .build();
  },
})
async createEvent(args: CreateEventInput) {
  // Implementation
  return { eventId: '123', ...args };
}

Core Package

CLI Package

Auth Package

Elicitation Package

UI Package

Utilities

Form Types & Validation

ElicitationField

Field Schema

Field Types

text

textarea

number

boolean

select

multiselect

email

url

date

FieldValidation

Validation Examples

Text Length Validation

Pattern Validation

Range Validation

Custom Validation

ValidationBuilder

Methods

Usage Example

ElicitationFormBuilder

Methods

Complete Example

Build docs developers (and LLMs) love

Core Package

CLI Package

Auth Package

Elicitation Package

UI Package

Utilities

​ElicitationField

​Field Schema

​Field Types

​text

​textarea

​number

​boolean

​select

​multiselect

​email

​url

​date

​FieldValidation

​Validation Examples

​Text Length Validation

​Pattern Validation

​Range Validation

​Custom Validation

​ValidationBuilder

​Methods

​Usage Example

​ElicitationFormBuilder

​Methods

​Complete Example

Build docs developers (and LLMs) love

ElicitationField

Field Schema

Field Types

text

textarea

number

boolean

select

multiselect

email

url

date

FieldValidation

Validation Examples

Text Length Validation

Pattern Validation

Range Validation

Custom Validation

ValidationBuilder

Methods

Usage Example

ElicitationFormBuilder

Methods

Complete Example