@leanmcp/elicitation 0.1.0

package/dist/index.mjs

@@ -0,0 +1,665 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+
+// src/types.ts
+import "reflect-metadata";
+var ElicitationError = class extends Error {
+  static {
+    __name(this, "ElicitationError");
+  }
+  code;
+  details;
+  constructor(message, code, details) {
+    super(message), this.code = code, this.details = details;
+    this.name = "ElicitationError";
+  }
+};
+
+// src/decorators.ts
+import "reflect-metadata";
+
+// src/strategies/base.ts
+var ElicitationStrategyBase = class {
+  static {
+    __name(this, "ElicitationStrategyBase");
+  }
+  /**
+  * Validate user response against field definitions
+  */
+  validateResponse(response, fields) {
+    const errors = [];
+    for (const field of fields) {
+      const value = response.values[field.name];
+      if (field.required && (value === void 0 || value === null || value === "")) {
+        errors.push({
+          field: field.name,
+          message: field.validation?.errorMessage || `${field.label} is required`
+        });
+        continue;
+      }
+      if (value === void 0 || value === null || value === "") {
+        continue;
+      }
+      const typeError = this.validateFieldType(value, field);
+      if (typeError) {
+        errors.push(typeError);
+        continue;
+      }
+      if (field.validation) {
+        const validationError = this.validateField(value, field);
+        if (validationError) {
+          errors.push(validationError);
+        }
+      }
+    }
+    return errors;
+  }
+  /**
+  * Validate field type
+  */
+  validateFieldType(value, field) {
+    switch (field.type) {
+      case "number":
+        if (typeof value !== "number" && isNaN(Number(value))) {
+          return {
+            field: field.name,
+            message: `${field.label} must be a number`
+          };
+        }
+        break;
+      case "boolean":
+        if (typeof value !== "boolean") {
+          return {
+            field: field.name,
+            message: `${field.label} must be true or false`
+          };
+        }
+        break;
+      case "email":
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(String(value))) {
+          return {
+            field: field.name,
+            message: `${field.label} must be a valid email address`
+          };
+        }
+        break;
+      case "url":
+        try {
+          new URL(String(value));
+        } catch {
+          return {
+            field: field.name,
+            message: `${field.label} must be a valid URL`
+          };
+        }
+        break;
+    }
+    return null;
+  }
+  /**
+  * Validate field against validation rules
+  */
+  validateField(value, field) {
+    const validation2 = field.validation;
+    if (!validation2) return null;
+    if (field.type === "number") {
+      const numValue = Number(value);
+      if (validation2.min !== void 0 && numValue < validation2.min) {
+        return {
+          field: field.name,
+          message: validation2.errorMessage || `${field.label} must be at least ${validation2.min}`
+        };
+      }
+      if (validation2.max !== void 0 && numValue > validation2.max) {
+        return {
+          field: field.name,
+          message: validation2.errorMessage || `${field.label} must be at most ${validation2.max}`
+        };
+      }
+    }
+    if (field.type === "text" || field.type === "textarea" || field.type === "email" || field.type === "url") {
+      const strValue = String(value);
+      if (validation2.minLength !== void 0 && strValue.length < validation2.minLength) {
+        return {
+          field: field.name,
+          message: validation2.errorMessage || `${field.label} must be at least ${validation2.minLength} characters`
+        };
+      }
+      if (validation2.maxLength !== void 0 && strValue.length > validation2.maxLength) {
+        return {
+          field: field.name,
+          message: validation2.errorMessage || `${field.label} must be at most ${validation2.maxLength} characters`
+        };
+      }
+    }
+    if (validation2.pattern) {
+      const regex = new RegExp(validation2.pattern);
+      if (!regex.test(String(value))) {
+        return {
+          field: field.name,
+          message: validation2.errorMessage || `${field.label} format is invalid`
+        };
+      }
+    }
+    if (validation2.customValidator) {
+      const result = validation2.customValidator(value);
+      if (result !== true) {
+        return {
+          field: field.name,
+          message: typeof result === "string" ? result : validation2.errorMessage || `${field.label} is invalid`
+        };
+      }
+    }
+    return null;
+  }
+  /**
+  * Merge elicited values with original arguments
+  */
+  mergeWithArgs(originalArgs, elicitedValues) {
+    return {
+      ...originalArgs,
+      ...elicitedValues
+    };
+  }
+};
+
+// src/strategies/form.ts
+var FormElicitationStrategy = class extends ElicitationStrategyBase {
+  static {
+    __name(this, "FormElicitationStrategy");
+  }
+  buildRequest(config, context) {
+    return {
+      type: "elicitation",
+      title: config.title || "Additional Information Required",
+      description: config.description,
+      fields: config.fields || [],
+      metadata: {
+        strategy: "form",
+        previousValues: context.args
+      }
+    };
+  }
+};
+
+// src/strategies/multi-step.ts
+var MultiStepElicitationStrategy = class extends ElicitationStrategyBase {
+  static {
+    __name(this, "MultiStepElicitationStrategy");
+  }
+  steps;
+  currentStep = 0;
+  accumulatedValues = {};
+  constructor(steps) {
+    super();
+    this.steps = steps;
+  }
+  buildRequest(config, context) {
+    while (this.currentStep < this.steps.length) {
+      const step = this.steps[this.currentStep];
+      if (!step.condition || step.condition(this.accumulatedValues)) {
+        return {
+          type: "elicitation",
+          title: step.title,
+          description: step.description,
+          fields: step.fields,
+          metadata: {
+            strategy: "multi-step",
+            stepNumber: this.currentStep + 1,
+            totalSteps: this.steps.length,
+            previousValues: {
+              ...context.args,
+              ...this.accumulatedValues
+            }
+          }
+        };
+      }
+      this.currentStep++;
+    }
+    return {
+      type: "elicitation",
+      title: "Complete",
+      description: "All steps completed",
+      fields: [],
+      metadata: {
+        strategy: "multi-step",
+        stepNumber: this.steps.length,
+        totalSteps: this.steps.length,
+        previousValues: this.accumulatedValues
+      }
+    };
+  }
+  /**
+  * Check if there are more steps
+  */
+  hasNextStep() {
+    return this.currentStep < this.steps.length - 1;
+  }
+  /**
+  * Move to next step and accumulate values
+  */
+  nextStep(values) {
+    this.accumulatedValues = {
+      ...this.accumulatedValues,
+      ...values
+    };
+    this.currentStep++;
+  }
+  /**
+  * Get all accumulated values
+  */
+  getAccumulatedValues() {
+    return {
+      ...this.accumulatedValues
+    };
+  }
+  /**
+  * Reset to first step
+  */
+  reset() {
+    this.currentStep = 0;
+    this.accumulatedValues = {};
+  }
+  /**
+  * Override merge to include all accumulated values
+  */
+  mergeWithArgs(originalArgs, elicitedValues) {
+    return {
+      ...originalArgs,
+      ...this.accumulatedValues,
+      ...elicitedValues
+    };
+  }
+};
+
+// src/decorators.ts
+function checkMissingFields(args, config) {
+  if (!config.fields) return false;
+  for (const field of config.fields) {
+    if (field.required) {
+      const value = args[field.name];
+      if (value === void 0 || value === null || value === "") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+__name(checkMissingFields, "checkMissingFields");
+function Elicitation(config) {
+  return (target, propertyKey, descriptor) => {
+    if (!descriptor || typeof descriptor.value !== "function") {
+      throw new Error("@Elicitation can only be applied to methods");
+    }
+    const originalMethod = descriptor.value;
+    Reflect.defineMetadata("elicitation:config", config, originalMethod);
+    Reflect.defineMetadata("elicitation:enabled", true, originalMethod);
+    const strategy = config.strategy || "form";
+    Reflect.defineMetadata("elicitation:strategy", strategy, originalMethod);
+    descriptor.value = async function(args, meta) {
+      const context = {
+        args: args || {},
+        meta,
+        previousAttempts: 0
+      };
+      if (config.condition && !config.condition(args || {})) {
+        return originalMethod.call(this, args, meta);
+      }
+      let needsElicitation = false;
+      let fieldsToCheck = [];
+      if (config.builder) {
+        const builtConfig = config.builder(context);
+        if (builtConfig && typeof builtConfig === "object" && "fields" in builtConfig) {
+          fieldsToCheck = builtConfig.fields || [];
+        } else if (Array.isArray(builtConfig)) {
+          const firstStep = builtConfig[0];
+          if (firstStep && firstStep.fields) {
+            fieldsToCheck = firstStep.fields;
+          }
+        }
+      } else if (config.fields) {
+        fieldsToCheck = config.fields;
+      }
+      for (const field of fieldsToCheck) {
+        if (field.required) {
+          const value = args[field.name];
+          if (value === void 0 || value === null || value === "") {
+            needsElicitation = true;
+            break;
+          }
+        }
+      }
+      if (needsElicitation) {
+        const elicitationRequest = buildElicitationRequestInternal(config, context);
+        return elicitationRequest;
+      }
+      return originalMethod.call(this, args, meta);
+    };
+    if (descriptor.value && typeof descriptor.value === "function") {
+      copyMethodMetadata(originalMethod, descriptor.value);
+    }
+  };
+}
+__name(Elicitation, "Elicitation");
+function copyMethodMetadata(source, target) {
+  const metadataKeys = Reflect.getMetadataKeys(source) || [];
+  for (const key of metadataKeys) {
+    const value = Reflect.getMetadata(key, source);
+    if (value !== void 0) {
+      Reflect.defineMetadata(key, value, target);
+    }
+  }
+}
+__name(copyMethodMetadata, "copyMethodMetadata");
+function buildElicitationRequestInternal(config, context) {
+  if (config.builder) {
+    const result = config.builder(context);
+    if (Array.isArray(result)) {
+      const strategy = new MultiStepElicitationStrategy(result);
+      return strategy.buildRequest(config, context);
+    }
+    if (result && typeof result === "object" && "fields" in result) {
+      const builtConfig = result;
+      const strategy = new FormElicitationStrategy();
+      return strategy.buildRequest(builtConfig, context);
+    }
+    return result;
+  }
+  const strategyType = config.strategy || "form";
+  switch (strategyType) {
+    case "form": {
+      const strategy = new FormElicitationStrategy();
+      return strategy.buildRequest(config, context);
+    }
+    case "multi-step": {
+      if (!config.fields) {
+        throw new Error("Multi-step elicitation requires either a builder or fields");
+      }
+      const steps = [
+        {
+          title: config.title || "Step 1",
+          description: config.description,
+          fields: config.fields
+        }
+      ];
+      const strategy = new MultiStepElicitationStrategy(steps);
+      return strategy.buildRequest(config, context);
+    }
+    default:
+      throw new Error(`Unsupported elicitation strategy: ${strategyType}`);
+  }
+}
+__name(buildElicitationRequestInternal, "buildElicitationRequestInternal");
+function isElicitationEnabled(method) {
+  return Reflect.getMetadata("elicitation:enabled", method) === true;
+}
+__name(isElicitationEnabled, "isElicitationEnabled");
+function getElicitationConfig(method) {
+  return Reflect.getMetadata("elicitation:config", method);
+}
+__name(getElicitationConfig, "getElicitationConfig");
+function getElicitationStrategy(method) {
+  return Reflect.getMetadata("elicitation:strategy", method);
+}
+__name(getElicitationStrategy, "getElicitationStrategy");
+function buildElicitationRequest(method, args, meta) {
+  const config = getElicitationConfig(method);
+  if (!config) return null;
+  const context = {
+    args,
+    meta,
+    previousAttempts: 0
+  };
+  if (config.condition && !config.condition(args)) {
+    return null;
+  }
+  if (config.builder) {
+    const result = config.builder(context);
+    if (Array.isArray(result)) {
+      const strategy = new MultiStepElicitationStrategy(result);
+      return strategy.buildRequest(config, context);
+    }
+    return result;
+  }
+  const strategyType = config.strategy || "form";
+  switch (strategyType) {
+    case "form": {
+      const strategy = new FormElicitationStrategy();
+      return strategy.buildRequest(config, context);
+    }
+    case "multi-step": {
+      if (!config.fields) {
+        throw new Error("Multi-step elicitation requires either a builder or fields");
+      }
+      const steps = [
+        {
+          title: config.title || "Step 1",
+          description: config.description,
+          fields: config.fields
+        }
+      ];
+      const strategy = new MultiStepElicitationStrategy(steps);
+      return strategy.buildRequest(config, context);
+    }
+    default:
+      throw new Error(`Unsupported elicitation strategy: ${strategyType}`);
+  }
+}
+__name(buildElicitationRequest, "buildElicitationRequest");
+
+// src/builders/form-builder.ts
+var ElicitationFormBuilder = class {
+  static {
+    __name(this, "ElicitationFormBuilder");
+  }
+  fields = [];
+  config = {};
+  /**
+  * Set the form title
+  */
+  title(title) {
+    this.config.title = title;
+    return this;
+  }
+  /**
+  * Set the form description
+  */
+  description(description) {
+    this.config.description = description;
+    return this;
+  }
+  /**
+  * Set a condition for when elicitation should occur
+  */
+  condition(condition) {
+    this.config.condition = condition;
+    return this;
+  }
+  /**
+  * Add a text field
+  */
+  addTextField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "text",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a textarea field
+  */
+  addTextAreaField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "textarea",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a number field
+  */
+  addNumberField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "number",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a boolean field (checkbox)
+  */
+  addBooleanField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "boolean",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a select field (dropdown)
+  */
+  addSelectField(name, label, options, fieldOptions) {
+    this.fields.push({
+      name,
+      label,
+      type: "select",
+      options,
+      ...fieldOptions
+    });
+    return this;
+  }
+  /**
+  * Add a multi-select field
+  */
+  addMultiSelectField(name, label, options, fieldOptions) {
+    this.fields.push({
+      name,
+      label,
+      type: "multiselect",
+      options,
+      ...fieldOptions
+    });
+    return this;
+  }
+  /**
+  * Add an email field
+  */
+  addEmailField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "email",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a URL field
+  */
+  addUrlField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "url",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a date field
+  */
+  addDateField(name, label, options) {
+    this.fields.push({
+      name,
+      label,
+      type: "date",
+      ...options
+    });
+    return this;
+  }
+  /**
+  * Add a custom field with full control
+  */
+  addCustomField(field) {
+    this.fields.push(field);
+    return this;
+  }
+  /**
+  * Build the final configuration
+  */
+  build() {
+    return {
+      ...this.config,
+      fields: this.fields,
+      strategy: "form"
+    };
+  }
+};
+var ValidationBuilder = class {
+  static {
+    __name(this, "ValidationBuilder");
+  }
+  validation = {};
+  min(min) {
+    this.validation.min = min;
+    return this;
+  }
+  max(max) {
+    this.validation.max = max;
+    return this;
+  }
+  minLength(minLength) {
+    this.validation.minLength = minLength;
+    return this;
+  }
+  maxLength(maxLength) {
+    this.validation.maxLength = maxLength;
+    return this;
+  }
+  pattern(pattern) {
+    this.validation.pattern = pattern;
+    return this;
+  }
+  customValidator(validator) {
+    this.validation.customValidator = validator;
+    return this;
+  }
+  errorMessage(message) {
+    this.validation.errorMessage = message;
+    return this;
+  }
+  build() {
+    return this.validation;
+  }
+};
+function validation() {
+  return new ValidationBuilder();
+}
+__name(validation, "validation");
+export {
+  Elicitation,
+  ElicitationError,
+  ElicitationFormBuilder,
+  ElicitationStrategyBase,
+  FormElicitationStrategy,
+  MultiStepElicitationStrategy,
+  ValidationBuilder,
+  buildElicitationRequest,
+  checkMissingFields,
+  getElicitationConfig,
+  getElicitationStrategy,
+  isElicitationEnabled,
+  validation
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@leanmcp/elicitation",
+  "version": "0.1.0",
+  "description": "Elicitation support for LeanMCP - structured user input collection",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@leanmcp/core": "*"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "typescript",
+    "decorators",
+    "elicitation",
+    "forms",
+    "validation",
+    "user-input",
+    "leanmcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LeanMCP/leanmcp-sdk.git",
+    "directory": "packages/elicitation"
+  },
+  "homepage": "https://github.com/LeanMCP/leanmcp-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/LeanMCP/leanmcp-sdk/issues"
+  },
+  "author": "LeanMCP <admin@leanmcp.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}