@papicandela/mcx-core 0.2.5 → 0.2.7

package/dist/index.js

@@ -6488,13 +6488,62 @@ class BunWorkerSandbox {
         return arr.slice(0, n);
       };
 
+      /**
+       * Poll a function until condition is met or max iterations reached.
+       * @param fn - Async function to call. Return { done: true, value } to stop.
+       * @param opts - { interval: ms (default 1000), maxIterations: n (default 10) }
+       * @returns Array of all results, or last result if done:true was returned
+       */
+      globalThis.poll = async (fn, opts = {}) => {
+        const interval = opts.interval ?? 1000;
+        const maxIterations = opts.maxIterations ?? 10;
+        const results = [];
+
+        for (let i = 0; i < maxIterations; i++) {
+          const result = await fn(i);
+          results.push(result);
+
+          // Check for done signal
+          if (result && typeof result === 'object' && result.done) {
+            return result.value !== undefined ? result.value : results;
+          }
+
+          // Wait before next iteration (skip on last)
+          if (i < maxIterations - 1) {
+            await new Promise(r => setTimeout(r, interval));
+          }
+        }
+
+        return results;
+      };
+
+      /**
+       * Wait for a condition to become true.
+       * @param fn - Async function that returns truthy when done
+       * @param opts - { interval: ms (default 500), timeout: ms (default 10000) }
+       * @returns The truthy value returned by fn
+       */
+      globalThis.waitFor = async (fn, opts = {}) => {
+        const interval = opts.interval ?? 500;
+        const timeout = opts.timeout ?? 10000;
+        const start = Date.now();
+
+        while (Date.now() - start < timeout) {
+          const result = await fn();
+          if (result) return result;
+          await new Promise(r => setTimeout(r, interval));
+        }
+
+        throw new Error('waitFor timeout after ' + timeout + 'ms');
+      };
+
       // SECURITY: Reserved keys that must not be overwritten by user-provided variables/globals
       const RESERVED_KEYS = new Set([
         'onmessage', 'postMessage', 'close', 'terminate', 'self',
         'constructor', 'prototype', '__proto__',
         'pendingCalls', 'callId', 'logs', 'console', 'adapters',
         'fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource',
-        'pick', 'table', 'count', 'sum', 'first', 'safeStr'
+        'pick', 'table', 'count', 'sum', 'first', 'safeStr', 'poll', 'waitFor'
       ]);
 
       self.onmessage = async (event) => {
@@ -6521,12 +6570,62 @@ class BunWorkerSandbox {
             globalThis[key] = value;
           }
 
-          // Create adapter proxies and freeze them to prevent user code modification
+          // Levenshtein distance for fuzzy matching
+          const levenshtein = (a, b) => {
+            if (a.length === 0) return b.length;
+            if (b.length === 0) return a.length;
+            const matrix = [];
+            for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+            for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+            for (let i = 1; i <= b.length; i++) {
+              for (let j = 1; j <= a.length; j++) {
+                matrix[i][j] = b[i-1] === a[j-1]
+                  ? matrix[i-1][j-1]
+                  : Math.min(matrix[i-1][j-1] + 1, matrix[i][j-1] + 1, matrix[i-1][j] + 1);
+              }
+            }
+            return matrix[b.length][a.length];
+          };
+
+          // Convert camelCase to snake_case
+          const toSnakeCase = (str) => str
+            .replace(/([a-z])([A-Z])/g, '$1_$2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+            .toLowerCase();
+
+          // Find similar method names
+          const findSimilar = (name, methods, maxDist = 3) => {
+            const normalized = name.toLowerCase().replace(/[-_]/g, '');
+            return methods
+              .map(m => ({ method: m, dist: levenshtein(normalized, m.toLowerCase().replace(/[-_]/g, '')) }))
+              .filter(x => x.dist <= maxDist)
+              .sort((a, b) => a.dist - b.dist)
+              .slice(0, 3)
+              .map(x => x.method);
+          };
+
+          // Find best auto-correctable match (distance ≤ 2 = safe to auto-correct)
+          const findAutoCorrect = (name, methods) => {
+            // Try exact snake_case conversion first
+            const snake = toSnakeCase(name);
+            if (methods.includes(snake)) return snake;
+
+            // Try normalized fuzzy match
+            const normalized = name.toLowerCase().replace(/[-_]/g, '');
+            const matches = methods
+              .map(m => ({ method: m, dist: levenshtein(normalized, m.toLowerCase().replace(/[-_]/g, '')) }))
+              .filter(x => x.dist <= 2) // Only auto-correct if very close
+              .sort((a, b) => a.dist - b.dist);
+
+            return matches.length > 0 ? matches[0].method : null;
+          };
+
+          // Create adapter proxies with helpful error messages
           const adaptersObj = {};
           for (const [adapterName, methods] of Object.entries(adapterMethods)) {
-            const adapterObj = {};
+            const methodsImpl = {};
             for (const methodName of methods) {
-              adapterObj[methodName] = async (...args) => {
+              methodsImpl[methodName] = async (...args) => {
                 const id = ++callId;
                 return new Promise((resolve, reject) => {
                   pendingCalls.set(id, { resolve, reject });
@@ -6540,18 +6639,57 @@ class BunWorkerSandbox {
                 });
               };
             }
-            // Freeze individual adapter to prevent method tampering
-            Object.freeze(adapterObj);
-            adaptersObj[adapterName] = adapterObj;
+
+            // Precompute auto-correct lookup (O(1) instead of O(n) per access)
+            const autoCorrectMap = new Map();
+            for (const m of methods) {
+              // Map snake_case variants: execute_sql -> execute_sql (identity)
+              autoCorrectMap.set(m, m);
+              // Map normalized: executesql -> execute_sql
+              autoCorrectMap.set(m.toLowerCase().replace(/[-_]/g, ''), m);
+            }
+
+            // Use Proxy to intercept undefined method calls with auto-correction
+            const adapterProxy = new Proxy(methodsImpl, {
+              get(target, prop) {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'symbol') return undefined;
+
+                const propStr = String(prop);
+
+                // Fast path: check precomputed map (O(1))
+                const snake = toSnakeCase(propStr);
+                if (autoCorrectMap.has(snake)) {
+                  return target[autoCorrectMap.get(snake)];
+                }
+                const normalized = propStr.toLowerCase().replace(/[-_]/g, '');
+                if (autoCorrectMap.has(normalized)) {
+                  return target[autoCorrectMap.get(normalized)];
+                }
+
+                // Slow path: fuzzy match for typos (only if fast path failed)
+                const corrected = findAutoCorrect(propStr, methods);
+                if (corrected && corrected in target) {
+                  return target[corrected];
+                }
+
+                // No auto-correct possible, throw with suggestions
+                const similar = findSimilar(propStr, methods);
+                const suggestion = similar.length > 0
+                  ? '. Did you mean: ' + similar.join(', ') + '?'
+                  : '. Available: ' + methods.slice(0, 5).join(', ') + (methods.length > 5 ? '...' : '');
+                throw new Error(adapterName + '.' + propStr + ' is not a function' + suggestion);
+              }
+            });
+
+            adaptersObj[adapterName] = adapterProxy;
             // Also expose at top level but as non-writable
             Object.defineProperty(globalThis, adapterName, {
-              value: adapterObj,
+              value: adapterProxy,
               writable: false,
               configurable: false
             });
           }
-          // Freeze the adapters namespace and make it non-writable
-          Object.freeze(adaptersObj);
           Object.defineProperty(globalThis, 'adapters', {
             value: adaptersObj,
             writable: false,
@@ -6577,7 +6715,23 @@ class BunWorkerSandbox {
             const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
             const fn = new AsyncFunction(data.code);
             const result = await fn();
-            self.postMessage({ type: 'result', success: true, value: result, logs });
+
+            // SECURITY: Hard cap on output size to prevent OOM
+            const HARD_CAP_BYTES = 100 * 1024 * 1024; // 100MB
+            const serialized = safeStr(result);
+            if (serialized.length > HARD_CAP_BYTES) {
+              self.postMessage({
+                type: 'result',
+                success: false,
+                error: {
+                  name: 'OutputSizeError',
+                  message: 'Output exceeds 100MB limit. Use pagination or filtering.'
+                },
+                logs
+              });
+            } else {
+              self.postMessage({ type: 'result', success: true, value: result, logs });
+            }
           } catch (err) {
             // Truncate stack to 5 lines to prevent context bloat
             const stack = err.stack ? err.stack.split('\\n').slice(0, 5).join('\\n') : undefined;
@@ -10867,12 +11021,54 @@ function generateTypes(adapters, options = {}) {
 `).trim();
 }
 function generateTypesSummary(adapters) {
-  return adapters.map((adapter) => {
-    const count = Object.keys(adapter.tools).length;
-    return `- ${adapter.name} (${count} methods)`;
-  }).join(`
+  const byDomain = new Map;
+  for (const adapter of adapters) {
+    const domain = inferDomain(adapter);
+    if (!byDomain.has(domain)) {
+      byDomain.set(domain, []);
+    }
+    byDomain.get(domain).push(adapter);
+  }
+  if (byDomain.size <= 1 || adapters.length < 4) {
+    return adapters.map((adapter) => {
+      const count = Object.keys(adapter.tools).length;
+      return `- ${adapter.name} (${count} methods)`;
+    }).join(`
+`);
+  }
+  const lines = [];
+  for (const [domain, domainAdapters] of byDomain) {
+    const adapterList = domainAdapters.map((a) => `${a.name}(${Object.keys(a.tools).length})`).join(", ");
+    lines.push(`[${domain}] ${adapterList}`);
+  }
+  return lines.join(`
 `);
 }
+function inferDomain(adapter) {
+  if (adapter.domain)
+    return adapter.domain;
+  const name = adapter.name.toLowerCase();
+  const desc = (adapter.description || "").toLowerCase();
+  const combined = `${name} ${desc}`;
+  const domains = {
+    payments: ["stripe", "paypal", "square", "payment", "checkout", "billing", "invoice"],
+    database: ["supabase", "postgres", "mysql", "mongodb", "redis", "database", "sql", "query"],
+    email: ["sendgrid", "mailgun", "postmark", "email", "smtp", "mail"],
+    storage: ["s3", "cloudflare", "storage", "blob", "file", "upload"],
+    auth: ["auth", "oauth", "login", "jwt", "clerk", "auth0"],
+    ai: ["openai", "anthropic", "claude", "gpt", "llm", "ai", "ml"],
+    messaging: ["slack", "discord", "telegram", "twilio", "sms", "chat"],
+    crm: ["hubspot", "salesforce", "crm", "customer"],
+    analytics: ["analytics", "metrics", "tracking", "mixpanel", "amplitude"],
+    devtools: ["github", "gitlab", "jira", "linear", "chrome", "devtools", "ci", "cd"]
+  };
+  for (const [domain, keywords2] of Object.entries(domains)) {
+    if (keywords2.some((k) => combined.includes(k))) {
+      return domain;
+    }
+  }
+  return "general";
+}
 function generateInputInterface(typeName, parameters, includeDescriptions) {
   const lines = [`interface ${typeName} {`];
   for (const [paramName, param] of Object.entries(parameters)) {
@@ -10881,7 +11077,7 @@ function generateInputInterface(typeName, parameters, includeDescriptions) {
       lines.push(`  /** ${sanitizeJSDoc(param.description)} */`);
     }
     const tsType = paramTypeToTS(param.type);
-    const optional = param.required === false ? "?" : "";
+    const optional = param.required === true ? "" : "?";
     lines.push(`  ${safeParamName}${optional}: ${tsType};`);
   }
   lines.push("}");
@@ -11170,6 +11366,7 @@ export {
   normalizeCode,
   mergeConfigs,
   isUrlAllowed,
+  inferDomain,
   generateTypesSummary,
   generateTypes,
   formatFindings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papicandela/mcx-core",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "MCX Core - MCP Code Execution Framework",
   "author": "papicandela",
   "license": "MIT",

package/src/index.ts

@@ -78,6 +78,7 @@ export { configBuilder, defineConfig, mergeConfigs } from "./config.js";
 export {
   generateTypes,
   generateTypesSummary,
+  inferDomain,
   sanitizeIdentifier,
   type TypeGeneratorOptions,
 } from "./type-generator.js";

package/src/sandbox/bun-worker.ts

@@ -285,13 +285,62 @@ export class BunWorkerSandbox implements ISandbox {
         return arr.slice(0, n);
       };
 
+      /**
+       * Poll a function until condition is met or max iterations reached.
+       * @param fn - Async function to call. Return { done: true, value } to stop.
+       * @param opts - { interval: ms (default 1000), maxIterations: n (default 10) }
+       * @returns Array of all results, or last result if done:true was returned
+       */
+      globalThis.poll = async (fn, opts = {}) => {
+        const interval = opts.interval ?? 1000;
+        const maxIterations = opts.maxIterations ?? 10;
+        const results = [];
+
+        for (let i = 0; i < maxIterations; i++) {
+          const result = await fn(i);
+          results.push(result);
+
+          // Check for done signal
+          if (result && typeof result === 'object' && result.done) {
+            return result.value !== undefined ? result.value : results;
+          }
+
+          // Wait before next iteration (skip on last)
+          if (i < maxIterations - 1) {
+            await new Promise(r => setTimeout(r, interval));
+          }
+        }
+
+        return results;
+      };
+
+      /**
+       * Wait for a condition to become true.
+       * @param fn - Async function that returns truthy when done
+       * @param opts - { interval: ms (default 500), timeout: ms (default 10000) }
+       * @returns The truthy value returned by fn
+       */
+      globalThis.waitFor = async (fn, opts = {}) => {
+        const interval = opts.interval ?? 500;
+        const timeout = opts.timeout ?? 10000;
+        const start = Date.now();
+
+        while (Date.now() - start < timeout) {
+          const result = await fn();
+          if (result) return result;
+          await new Promise(r => setTimeout(r, interval));
+        }
+
+        throw new Error('waitFor timeout after ' + timeout + 'ms');
+      };
+
       // SECURITY: Reserved keys that must not be overwritten by user-provided variables/globals
       const RESERVED_KEYS = new Set([
         'onmessage', 'postMessage', 'close', 'terminate', 'self',
         'constructor', 'prototype', '__proto__',
         'pendingCalls', 'callId', 'logs', 'console', 'adapters',
         'fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource',
-        'pick', 'table', 'count', 'sum', 'first', 'safeStr'
+        'pick', 'table', 'count', 'sum', 'first', 'safeStr', 'poll', 'waitFor'
       ]);
 
       self.onmessage = async (event) => {
@@ -318,12 +367,62 @@ export class BunWorkerSandbox implements ISandbox {
             globalThis[key] = value;
           }
 
-          // Create adapter proxies and freeze them to prevent user code modification
+          // Levenshtein distance for fuzzy matching
+          const levenshtein = (a, b) => {
+            if (a.length === 0) return b.length;
+            if (b.length === 0) return a.length;
+            const matrix = [];
+            for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+            for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+            for (let i = 1; i <= b.length; i++) {
+              for (let j = 1; j <= a.length; j++) {
+                matrix[i][j] = b[i-1] === a[j-1]
+                  ? matrix[i-1][j-1]
+                  : Math.min(matrix[i-1][j-1] + 1, matrix[i][j-1] + 1, matrix[i-1][j] + 1);
+              }
+            }
+            return matrix[b.length][a.length];
+          };
+
+          // Convert camelCase to snake_case
+          const toSnakeCase = (str) => str
+            .replace(/([a-z])([A-Z])/g, '$1_$2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+            .toLowerCase();
+
+          // Find similar method names
+          const findSimilar = (name, methods, maxDist = 3) => {
+            const normalized = name.toLowerCase().replace(/[-_]/g, '');
+            return methods
+              .map(m => ({ method: m, dist: levenshtein(normalized, m.toLowerCase().replace(/[-_]/g, '')) }))
+              .filter(x => x.dist <= maxDist)
+              .sort((a, b) => a.dist - b.dist)
+              .slice(0, 3)
+              .map(x => x.method);
+          };
+
+          // Find best auto-correctable match (distance ≤ 2 = safe to auto-correct)
+          const findAutoCorrect = (name, methods) => {
+            // Try exact snake_case conversion first
+            const snake = toSnakeCase(name);
+            if (methods.includes(snake)) return snake;
+
+            // Try normalized fuzzy match
+            const normalized = name.toLowerCase().replace(/[-_]/g, '');
+            const matches = methods
+              .map(m => ({ method: m, dist: levenshtein(normalized, m.toLowerCase().replace(/[-_]/g, '')) }))
+              .filter(x => x.dist <= 2) // Only auto-correct if very close
+              .sort((a, b) => a.dist - b.dist);
+
+            return matches.length > 0 ? matches[0].method : null;
+          };
+
+          // Create adapter proxies with helpful error messages
           const adaptersObj = {};
           for (const [adapterName, methods] of Object.entries(adapterMethods)) {
-            const adapterObj = {};
+            const methodsImpl = {};
             for (const methodName of methods) {
-              adapterObj[methodName] = async (...args) => {
+              methodsImpl[methodName] = async (...args) => {
                 const id = ++callId;
                 return new Promise((resolve, reject) => {
                   pendingCalls.set(id, { resolve, reject });
@@ -337,18 +436,57 @@ export class BunWorkerSandbox implements ISandbox {
                 });
               };
             }
-            // Freeze individual adapter to prevent method tampering
-            Object.freeze(adapterObj);
-            adaptersObj[adapterName] = adapterObj;
+
+            // Precompute auto-correct lookup (O(1) instead of O(n) per access)
+            const autoCorrectMap = new Map();
+            for (const m of methods) {
+              // Map snake_case variants: execute_sql -> execute_sql (identity)
+              autoCorrectMap.set(m, m);
+              // Map normalized: executesql -> execute_sql
+              autoCorrectMap.set(m.toLowerCase().replace(/[-_]/g, ''), m);
+            }
+
+            // Use Proxy to intercept undefined method calls with auto-correction
+            const adapterProxy = new Proxy(methodsImpl, {
+              get(target, prop) {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'symbol') return undefined;
+
+                const propStr = String(prop);
+
+                // Fast path: check precomputed map (O(1))
+                const snake = toSnakeCase(propStr);
+                if (autoCorrectMap.has(snake)) {
+                  return target[autoCorrectMap.get(snake)];
+                }
+                const normalized = propStr.toLowerCase().replace(/[-_]/g, '');
+                if (autoCorrectMap.has(normalized)) {
+                  return target[autoCorrectMap.get(normalized)];
+                }
+
+                // Slow path: fuzzy match for typos (only if fast path failed)
+                const corrected = findAutoCorrect(propStr, methods);
+                if (corrected && corrected in target) {
+                  return target[corrected];
+                }
+
+                // No auto-correct possible, throw with suggestions
+                const similar = findSimilar(propStr, methods);
+                const suggestion = similar.length > 0
+                  ? '. Did you mean: ' + similar.join(', ') + '?'
+                  : '. Available: ' + methods.slice(0, 5).join(', ') + (methods.length > 5 ? '...' : '');
+                throw new Error(adapterName + '.' + propStr + ' is not a function' + suggestion);
+              }
+            });
+
+            adaptersObj[adapterName] = adapterProxy;
             // Also expose at top level but as non-writable
             Object.defineProperty(globalThis, adapterName, {
-              value: adapterObj,
+              value: adapterProxy,
               writable: false,
               configurable: false
             });
           }
-          // Freeze the adapters namespace and make it non-writable
-          Object.freeze(adaptersObj);
           Object.defineProperty(globalThis, 'adapters', {
             value: adaptersObj,
             writable: false,
@@ -374,7 +512,23 @@ export class BunWorkerSandbox implements ISandbox {
             const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
             const fn = new AsyncFunction(data.code);
             const result = await fn();
-            self.postMessage({ type: 'result', success: true, value: result, logs });
+
+            // SECURITY: Hard cap on output size to prevent OOM
+            const HARD_CAP_BYTES = 100 * 1024 * 1024; // 100MB
+            const serialized = safeStr(result);
+            if (serialized.length > HARD_CAP_BYTES) {
+              self.postMessage({
+                type: 'result',
+                success: false,
+                error: {
+                  name: 'OutputSizeError',
+                  message: 'Output exceeds 100MB limit. Use pagination or filtering.'
+                },
+                logs
+              });
+            } else {
+              self.postMessage({ type: 'result', success: true, value: result, logs });
+            }
           } catch (err) {
             // Truncate stack to 5 lines to prevent context bloat
             const stack = err.stack ? err.stack.split('\\n').slice(0, 5).join('\\n') : undefined;

package/src/type-generator.ts

@@ -85,19 +85,76 @@ export function generateTypes(
 
 /**
  * Generate a compact type summary for token-constrained contexts.
- * Only shows adapter names and method count to minimize context usage.
+ * Groups adapters by domain and shows method count.
  * Use mcx_search to discover specific methods.
  *
  * @param adapters - Array of adapters
- * @returns Compact summary string
+ * @returns Compact summary string with domain hints
  */
 export function generateTypesSummary(adapters: Adapter[]): string {
-  return adapters
-    .map((adapter) => {
-      const count = Object.keys(adapter.tools).length;
-      return `- ${adapter.name} (${count} methods)`;
-    })
-    .join("\n");
+  // Group adapters by domain
+  const byDomain = new Map<string, Adapter[]>();
+
+  for (const adapter of adapters) {
+    const domain = inferDomain(adapter);
+    if (!byDomain.has(domain)) {
+      byDomain.set(domain, []);
+    }
+    byDomain.get(domain)!.push(adapter);
+  }
+
+  // If only one domain or fewer than 4 adapters, simple list
+  if (byDomain.size <= 1 || adapters.length < 4) {
+    return adapters
+      .map((adapter) => {
+        const count = Object.keys(adapter.tools).length;
+        return `- ${adapter.name} (${count} methods)`;
+      })
+      .join("\n");
+  }
+
+  // Group by domain for better discoverability
+  const lines: string[] = [];
+  for (const [domain, domainAdapters] of byDomain) {
+    const adapterList = domainAdapters
+      .map((a) => `${a.name}(${Object.keys(a.tools).length})`)
+      .join(", ");
+    lines.push(`[${domain}] ${adapterList}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Infer domain from adapter name/description if not explicitly set.
+ * Returns the adapter's explicit domain if set, otherwise infers from name/description.
+ */
+export function inferDomain(adapter: Adapter): string {
+  if (adapter.domain) return adapter.domain;
+
+  const name = adapter.name.toLowerCase();
+  const desc = (adapter.description || "").toLowerCase();
+  const combined = `${name} ${desc}`;
+
+  const domains: Record<string, string[]> = {
+    payments: ["stripe", "paypal", "square", "payment", "checkout", "billing", "invoice"],
+    database: ["supabase", "postgres", "mysql", "mongodb", "redis", "database", "sql", "query"],
+    email: ["sendgrid", "mailgun", "postmark", "email", "smtp", "mail"],
+    storage: ["s3", "cloudflare", "storage", "blob", "file", "upload"],
+    auth: ["auth", "oauth", "login", "jwt", "clerk", "auth0"],
+    ai: ["openai", "anthropic", "claude", "gpt", "llm", "ai", "ml"],
+    messaging: ["slack", "discord", "telegram", "twilio", "sms", "chat"],
+    crm: ["hubspot", "salesforce", "crm", "customer"],
+    analytics: ["analytics", "metrics", "tracking", "mixpanel", "amplitude"],
+    devtools: ["github", "gitlab", "jira", "linear", "chrome", "devtools", "ci", "cd"],
+  };
+
+  for (const [domain, keywords] of Object.entries(domains)) {
+    if (keywords.some((k) => combined.includes(k))) {
+      return domain;
+    }
+  }
+
+  return "general";
 }
 
 /**
@@ -119,7 +176,7 @@ function generateInputInterface(
     }
 
     const tsType = paramTypeToTS(param.type);
-    const optional = param.required === false ? "?" : "";
+    const optional = param.required === true ? "" : "?";
     lines.push(`  ${safeParamName}${optional}: ${tsType};`);
   }
 

package/src/types.ts

@@ -12,6 +12,8 @@ export interface ParameterDefinition {
   description?: string;
   required?: boolean;
   default?: unknown;
+  /** Example value for this parameter (helps LLMs understand expected format) */
+  example?: unknown;
 }
 
 /**
@@ -33,6 +35,8 @@ export interface Adapter<TTools extends Record<string, AdapterTool> = Record<str
   name: string;
   description?: string;
   version?: string;
+  /** Domain/category for tool discovery (e.g., 'payments', 'database', 'email') */
+  domain?: string;
   tools: TTools;
   dispose?: () => Promise<void> | void;
 }