@leanmcp/utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LeanMCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+# @leanmcp/utils
+
+Utility functions and helpers for LeanMCP SDK.
+
+## Features
+
+- 🔄 **Retry logic** - Exponential backoff for resilient operations
+- 📊 **Response formatting** - Format data as JSON, Markdown, HTML, or tables
+- 🔀 **Object utilities** - Deep merge, validation, and manipulation
+- ⏱️ **Async helpers** - Sleep, timeout, and promise utilities
+
+## Installation
+
+```bash
+npm install @leanmcp/utils
+```
+
+## API Reference
+
+### Response Formatting
+
+#### formatResponse(data, format)
+
+Format data based on specified format type.
+
+```typescript
+import { formatResponse } from "@leanmcp/utils";
+
+// JSON formatting
+const json = formatResponse({ hello: "world" }, "json");
+// Output: '{\n  "hello": "world"\n}'
+
+// Markdown formatting
+const md = formatResponse({ hello: "world" }, "markdown");
+// Output: '```json\n{\n  "hello": "world"\n}\n```'
+
+// HTML formatting
+const html = formatResponse({ hello: "world" }, "html");
+// Output: '<pre>{\n  "hello": "world"\n}</pre>'
+
+// Table formatting (for arrays)
+const table = formatResponse([
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 25 }
+], "table");
+// Output: Markdown table format
+```
+
+**Supported formats:**
+- `json` - Pretty-printed JSON
+- `markdown` - JSON wrapped in markdown code block
+- `html` - JSON wrapped in HTML pre tag
+- `table` - Markdown table (for arrays of objects)
+- Default - String conversion
+
+#### formatAsTable(data)
+
+Format array of objects as a Markdown table.
+
+```typescript
+import { formatAsTable } from "@leanmcp/utils";
+
+const data = [
+  { name: "Alice", age: 30, city: "NYC" },
+  { name: "Bob", age: 25, city: "LA" }
+];
+
+const table = formatAsTable(data);
+console.log(table);
+// | name | age | city |
+// | --- | --- | --- |
+// | Alice | 30 | NYC |
+// | Bob | 25 | LA |
+```
+
+### Object Utilities
+
+#### deepMerge(target, ...sources)
+
+Deep merge multiple objects.
+
+```typescript
+import { deepMerge } from "@leanmcp/utils";
+
+const target = { a: 1, b: { c: 2 } };
+const source1 = { b: { d: 3 } };
+const source2 = { e: 4 };
+
+const result = deepMerge(target, source1, source2);
+// { a: 1, b: { c: 2, d: 3 }, e: 4 }
+```
+
+#### isObject(item)
+
+Check if value is a plain object.
+
+```typescript
+import { isObject } from "@leanmcp/utils";
+
+isObject({});           // true
+isObject([]);           // false
+isObject(null);         // false
+isObject("string");     // false
+```
+
+### Async Utilities
+
+#### retry(fn, options)
+
+Retry a function with exponential backoff.
+
+```typescript
+import { retry } from "@leanmcp/utils";
+
+// Retry API call up to 3 times
+const result = await retry(
+  async () => {
+    const response = await fetch('https://api.example.com/data');
+    if (!response.ok) throw new Error('API error');
+    return response.json();
+  },
+  {
+    maxRetries: 3,       // Maximum number of retries
+    delayMs: 1000,       // Initial delay in milliseconds
+    backoff: 2           // Backoff multiplier (2^n)
+  }
+);
+```
+
+**Retry logic:**
+- Attempt 1: Immediate
+- Attempt 2: Wait 1000ms
+- Attempt 3: Wait 2000ms
+- Attempt 4: Wait 4000ms
+
+#### sleep(ms)
+
+Async sleep function.
+
+```typescript
+import { sleep } from "@leanmcp/utils";
+
+await sleep(1000);  // Wait 1 second
+console.log("1 second later");
+```
+
+#### timeout(promise, ms)
+
+Add timeout to a promise.
+
+```typescript
+import { timeout } from "@leanmcp/utils";
+
+try {
+  const result = await timeout(
+    fetch('https://slow-api.example.com'),
+    5000  // 5 second timeout
+  );
+} catch (error) {
+  console.log('Request timed out');
+}
+```
+
+## Usage Examples
+
+### Formatting API Responses
+
+```typescript
+import { formatResponse } from "@leanmcp/utils";
+
+class DataService {
+  @Tool({ description: 'Get user data' })
+  async getUsers() {
+    const users = await fetchUsers();
+    
+    // Return as formatted table
+    return {
+      content: [{
+        type: "text",
+        text: formatResponse(users, "table")
+      }]
+    };
+  }
+}
+```
+
+### Resilient API Calls
+
+```typescript
+import { retry } from "@leanmcp/utils";
+
+class ExternalService {
+  @Tool({ description: 'Fetch external data' })
+  async fetchData(input: { url: string }) {
+    // Automatically retry failed requests
+    const data = await retry(
+      () => fetch(input.url).then(r => r.json()),
+      { maxRetries: 3, delayMs: 1000 }
+    );
+    
+    return { data };
+  }
+}
+```
+
+### Deep Configuration Merging
+
+```typescript
+import { deepMerge } from "@leanmcp/utils";
+
+const defaultConfig = {
+  server: { port: 3000, host: 'localhost' },
+  logging: { level: 'info' }
+};
+
+const userConfig = {
+  server: { port: 4000 },
+  features: { auth: true }
+};
+
+const config = deepMerge(defaultConfig, userConfig);
+// {
+//   server: { port: 4000, host: 'localhost' },
+//   logging: { level: 'info' },
+//   features: { auth: true }
+// }
+```
+
+## Type Definitions
+
+All functions are fully typed with TypeScript:
+
+```typescript
+export function formatResponse(data: any, format: string): string;
+export function formatAsTable(data: any[]): string;
+export function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
+export function isObject(item: any): boolean;
+export function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export function sleep(ms: number): Promise<void>;
+export function timeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+
+interface RetryOptions {
+  maxRetries?: number;
+  delayMs?: number;
+  backoff?: number;
+}
+```
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@leanmcp/core](../core) - Core MCP server functionality
+- [@leanmcp/auth](../auth) - Authentication decorators
+- [@leanmcp/cli](../cli) - CLI tool for creating new projects
+
+## Links
+
+- [GitHub Repository](https://github.com/LeanMCP/leanmcp-sdk)
+- [Documentation](https://github.com/LeanMCP/leanmcp-sdk#readme)

package/dist/index.d.mts

@@ -0,0 +1,79 @@
+/**
+ * @leanmcp/utils - Utility Functions
+ *
+ * This module provides helper utilities and shared functions across the LeanMCP SDK.
+ */
+/**
+ * Validate JSON against a schema (basic implementation)
+ * For advanced validation, use ajv or similar libraries in your project
+ */
+declare function validateSchema(data: any, schema: any): {
+    valid: boolean;
+    errors?: any[];
+};
+/**
+ * Format response based on render type
+ */
+declare function formatResponse(data: any, format: string): string;
+/**
+ * Format data as a markdown table
+ */
+declare function formatAsTable(data: any[]): string;
+/**
+ * Deep merge objects
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Check if value is a plain object
+ */
+declare function isObject(item: any): boolean;
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    delayMs?: number;
+    backoff?: number;
+}): Promise<T>;
+/**
+ * Sleep for a given duration
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Create a debounced function
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, waitMs: number): (...args: Parameters<T>) => void;
+/**
+ * Create a throttled function
+ */
+declare function throttle<T extends (...args: any[]) => any>(func: T, limitMs: number): (...args: Parameters<T>) => void;
+/**
+ * Parse environment variables with type coercion
+ */
+declare function parseEnv(value: string | undefined, defaultValue: any, type?: 'string' | 'number' | 'boolean'): any;
+/**
+ * Generate a unique ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Truncate string to max length
+ */
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+/**
+ * Add timeout to a promise
+ */
+declare function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+/**
+ * Convert camelCase to kebab-case
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase
+ */
+declare function kebabToCamel(str: string): string;
+/**
+ * Capitalize first letter
+ */
+declare function capitalize(str: string): string;
+
+export { camelToKebab, capitalize, debounce, deepMerge, formatAsTable, formatResponse, generateId, isObject, kebabToCamel, parseEnv, retry, sleep, throttle, timeout, truncate, validateSchema };

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @leanmcp/utils - Utility Functions
+ *
+ * This module provides helper utilities and shared functions across the LeanMCP SDK.
+ */
+/**
+ * Validate JSON against a schema (basic implementation)
+ * For advanced validation, use ajv or similar libraries in your project
+ */
+declare function validateSchema(data: any, schema: any): {
+    valid: boolean;
+    errors?: any[];
+};
+/**
+ * Format response based on render type
+ */
+declare function formatResponse(data: any, format: string): string;
+/**
+ * Format data as a markdown table
+ */
+declare function formatAsTable(data: any[]): string;
+/**
+ * Deep merge objects
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Check if value is a plain object
+ */
+declare function isObject(item: any): boolean;
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    delayMs?: number;
+    backoff?: number;
+}): Promise<T>;
+/**
+ * Sleep for a given duration
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Create a debounced function
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, waitMs: number): (...args: Parameters<T>) => void;
+/**
+ * Create a throttled function
+ */
+declare function throttle<T extends (...args: any[]) => any>(func: T, limitMs: number): (...args: Parameters<T>) => void;
+/**
+ * Parse environment variables with type coercion
+ */
+declare function parseEnv(value: string | undefined, defaultValue: any, type?: 'string' | 'number' | 'boolean'): any;
+/**
+ * Generate a unique ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Truncate string to max length
+ */
+declare function truncate(str: string, maxLength: number, suffix?: string): string;
+/**
+ * Add timeout to a promise
+ */
+declare function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+/**
+ * Convert camelCase to kebab-case
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase
+ */
+declare function kebabToCamel(str: string): string;
+/**
+ * Capitalize first letter
+ */
+declare function capitalize(str: string): string;
+
+export { camelToKebab, capitalize, debounce, deepMerge, formatAsTable, formatResponse, generateId, isObject, kebabToCamel, parseEnv, retry, sleep, throttle, timeout, truncate, validateSchema };

package/dist/index.js

@@ -0,0 +1,229 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  camelToKebab: () => camelToKebab,
+  capitalize: () => capitalize,
+  debounce: () => debounce,
+  deepMerge: () => deepMerge,
+  formatAsTable: () => formatAsTable,
+  formatResponse: () => formatResponse,
+  generateId: () => generateId,
+  isObject: () => isObject,
+  kebabToCamel: () => kebabToCamel,
+  parseEnv: () => parseEnv,
+  retry: () => retry,
+  sleep: () => sleep,
+  throttle: () => throttle,
+  timeout: () => timeout,
+  truncate: () => truncate,
+  validateSchema: () => validateSchema
+});
+module.exports = __toCommonJS(index_exports);
+function validateSchema(data, schema) {
+  const errors = [];
+  if (!schema || typeof schema !== "object") {
+    return {
+      valid: true
+    };
+  }
+  if (schema.type) {
+    const actualType = Array.isArray(data) ? "array" : typeof data;
+    if (actualType !== schema.type && !(schema.type === "integer" && typeof data === "number")) {
+      errors.push({
+        message: `Expected type ${schema.type}, got ${actualType}`
+      });
+    }
+  }
+  if (schema.required && Array.isArray(schema.required) && typeof data === "object") {
+    for (const prop of schema.required) {
+      if (!(prop in data)) {
+        errors.push({
+          message: `Missing required property: ${prop}`
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : void 0
+  };
+}
+__name(validateSchema, "validateSchema");
+function formatResponse(data, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(data, null, 2);
+    case "markdown":
+      return typeof data === "string" ? data : `\`\`\`json
+${JSON.stringify(data, null, 2)}
+\`\`\``;
+    case "html":
+      return typeof data === "string" ? data : `<pre>${JSON.stringify(data, null, 2)}</pre>`;
+    case "table":
+      return formatAsTable(data);
+    default:
+      return String(data);
+  }
+}
+__name(formatResponse, "formatResponse");
+function formatAsTable(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    return String(data);
+  }
+  const keys = Object.keys(data[0]);
+  const header = `| ${keys.join(" | ")} |`;
+  const separator = `| ${keys.map(() => "---").join(" | ")} |`;
+  const rows = data.map((row) => `| ${keys.map((key) => row[key]).join(" | ")} |`);
+  return [
+    header,
+    separator,
+    ...rows
+  ].join("\n");
+}
+__name(formatAsTable, "formatAsTable");
+function deepMerge(target, ...sources) {
+  if (!sources.length) return target;
+  const source = sources.shift();
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, {
+          [key]: {}
+        });
+        deepMerge(target[key], source[key]);
+      } else {
+        Object.assign(target, {
+          [key]: source[key]
+        });
+      }
+    }
+  }
+  return deepMerge(target, ...sources);
+}
+__name(deepMerge, "deepMerge");
+function isObject(item) {
+  return item && typeof item === "object" && !Array.isArray(item);
+}
+__name(isObject, "isObject");
+async function retry(fn, options = {}) {
+  const { maxRetries = 3, delayMs = 1e3, backoff = 2 } = options;
+  let lastError;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (i < maxRetries - 1) {
+        await sleep(delayMs * Math.pow(backoff, i));
+      }
+    }
+  }
+  throw lastError;
+}
+__name(retry, "retry");
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+function debounce(func, waitMs) {
+  let timeout2 = null;
+  return function(...args) {
+    if (timeout2) clearTimeout(timeout2);
+    timeout2 = setTimeout(() => func.apply(this, args), waitMs);
+  };
+}
+__name(debounce, "debounce");
+function throttle(func, limitMs) {
+  let inThrottle = false;
+  return function(...args) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limitMs);
+    }
+  };
+}
+__name(throttle, "throttle");
+function parseEnv(value, defaultValue, type = "string") {
+  if (value === void 0) return defaultValue;
+  switch (type) {
+    case "number":
+      const num = Number(value);
+      return isNaN(num) ? defaultValue : num;
+    case "boolean":
+      return value.toLowerCase() === "true";
+    case "string":
+    default:
+      return value;
+  }
+}
+__name(parseEnv, "parseEnv");
+function generateId(prefix = "") {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 9);
+  return prefix ? `${prefix}-${timestamp}-${random}` : `${timestamp}-${random}`;
+}
+__name(generateId, "generateId");
+function truncate(str, maxLength, suffix = "...") {
+  if (str.length <= maxLength) return str;
+  return str.substring(0, maxLength - suffix.length) + suffix;
+}
+__name(truncate, "truncate");
+function timeout(promise, ms, errorMessage = "Operation timed out") {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error(errorMessage)), ms))
+  ]);
+}
+__name(timeout, "timeout");
+function camelToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+__name(camelToKebab, "camelToKebab");
+function kebabToCamel(str) {
+  return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+__name(kebabToCamel, "kebabToCamel");
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+__name(capitalize, "capitalize");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  camelToKebab,
+  capitalize,
+  debounce,
+  deepMerge,
+  formatAsTable,
+  formatResponse,
+  generateId,
+  isObject,
+  kebabToCamel,
+  parseEnv,
+  retry,
+  sleep,
+  throttle,
+  timeout,
+  truncate,
+  validateSchema
+});

package/dist/index.mjs

@@ -0,0 +1,191 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+function validateSchema(data, schema) {
+  const errors = [];
+  if (!schema || typeof schema !== "object") {
+    return {
+      valid: true
+    };
+  }
+  if (schema.type) {
+    const actualType = Array.isArray(data) ? "array" : typeof data;
+    if (actualType !== schema.type && !(schema.type === "integer" && typeof data === "number")) {
+      errors.push({
+        message: `Expected type ${schema.type}, got ${actualType}`
+      });
+    }
+  }
+  if (schema.required && Array.isArray(schema.required) && typeof data === "object") {
+    for (const prop of schema.required) {
+      if (!(prop in data)) {
+        errors.push({
+          message: `Missing required property: ${prop}`
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : void 0
+  };
+}
+__name(validateSchema, "validateSchema");
+function formatResponse(data, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(data, null, 2);
+    case "markdown":
+      return typeof data === "string" ? data : `\`\`\`json
+${JSON.stringify(data, null, 2)}
+\`\`\``;
+    case "html":
+      return typeof data === "string" ? data : `<pre>${JSON.stringify(data, null, 2)}</pre>`;
+    case "table":
+      return formatAsTable(data);
+    default:
+      return String(data);
+  }
+}
+__name(formatResponse, "formatResponse");
+function formatAsTable(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    return String(data);
+  }
+  const keys = Object.keys(data[0]);
+  const header = `| ${keys.join(" | ")} |`;
+  const separator = `| ${keys.map(() => "---").join(" | ")} |`;
+  const rows = data.map((row) => `| ${keys.map((key) => row[key]).join(" | ")} |`);
+  return [
+    header,
+    separator,
+    ...rows
+  ].join("\n");
+}
+__name(formatAsTable, "formatAsTable");
+function deepMerge(target, ...sources) {
+  if (!sources.length) return target;
+  const source = sources.shift();
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, {
+          [key]: {}
+        });
+        deepMerge(target[key], source[key]);
+      } else {
+        Object.assign(target, {
+          [key]: source[key]
+        });
+      }
+    }
+  }
+  return deepMerge(target, ...sources);
+}
+__name(deepMerge, "deepMerge");
+function isObject(item) {
+  return item && typeof item === "object" && !Array.isArray(item);
+}
+__name(isObject, "isObject");
+async function retry(fn, options = {}) {
+  const { maxRetries = 3, delayMs = 1e3, backoff = 2 } = options;
+  let lastError;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (i < maxRetries - 1) {
+        await sleep(delayMs * Math.pow(backoff, i));
+      }
+    }
+  }
+  throw lastError;
+}
+__name(retry, "retry");
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+function debounce(func, waitMs) {
+  let timeout2 = null;
+  return function(...args) {
+    if (timeout2) clearTimeout(timeout2);
+    timeout2 = setTimeout(() => func.apply(this, args), waitMs);
+  };
+}
+__name(debounce, "debounce");
+function throttle(func, limitMs) {
+  let inThrottle = false;
+  return function(...args) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limitMs);
+    }
+  };
+}
+__name(throttle, "throttle");
+function parseEnv(value, defaultValue, type = "string") {
+  if (value === void 0) return defaultValue;
+  switch (type) {
+    case "number":
+      const num = Number(value);
+      return isNaN(num) ? defaultValue : num;
+    case "boolean":
+      return value.toLowerCase() === "true";
+    case "string":
+    default:
+      return value;
+  }
+}
+__name(parseEnv, "parseEnv");
+function generateId(prefix = "") {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 9);
+  return prefix ? `${prefix}-${timestamp}-${random}` : `${timestamp}-${random}`;
+}
+__name(generateId, "generateId");
+function truncate(str, maxLength, suffix = "...") {
+  if (str.length <= maxLength) return str;
+  return str.substring(0, maxLength - suffix.length) + suffix;
+}
+__name(truncate, "truncate");
+function timeout(promise, ms, errorMessage = "Operation timed out") {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error(errorMessage)), ms))
+  ]);
+}
+__name(timeout, "timeout");
+function camelToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+__name(camelToKebab, "camelToKebab");
+function kebabToCamel(str) {
+  return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+__name(kebabToCamel, "kebabToCamel");
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+__name(capitalize, "capitalize");
+export {
+  camelToKebab,
+  capitalize,
+  debounce,
+  deepMerge,
+  formatAsTable,
+  formatResponse,
+  generateId,
+  isObject,
+  kebabToCamel,
+  parseEnv,
+  retry,
+  sleep,
+  throttle,
+  timeout,
+  truncate,
+  validateSchema
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@leanmcp/utils",
+  "version": "0.1.0",
+  "description": "Helper utilities and decorators shared across modules",
+  "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 esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@leanmcp/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LeanMCP/leanmcp-sdk.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://github.com/LeanMCP/leanmcp-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/LeanMCP/leanmcp-sdk/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "typescript",
+    "utilities",
+    "helpers",
+    "validation"
+  ],
+  "author": "LeanMCP <admin@leanmcp.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}