@papicandela/mcx-core 0.2.5 → 0.2.6

package/dist/index.js

@@ -6521,12 +6521,40 @@ 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];
+          };
+
+          // 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);
+          };
+
+          // 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 +6568,28 @@ class BunWorkerSandbox {
                 });
               };
             }
-            // Freeze individual adapter to prevent method tampering
-            Object.freeze(adapterObj);
-            adaptersObj[adapterName] = adapterObj;
+
+            // Use Proxy to intercept undefined method calls
+            const adapterProxy = new Proxy(methodsImpl, {
+              get(target, prop) {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'symbol') return undefined;
+                const similar = findSimilar(String(prop), methods);
+                const suggestion = similar.length > 0
+                  ? '. Did you mean: ' + similar.join(', ') + '?'
+                  : '. Available: ' + methods.slice(0, 5).join(', ') + (methods.length > 5 ? '...' : '');
+                throw new Error(adapterName + '.' + String(prop) + ' 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,
@@ -10867,11 +10905,53 @@ 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} {`];
@@ -10881,7 +10961,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 +11250,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.6",
   "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

@@ -318,12 +318,40 @@ 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];
+          };
+
+          // 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);
+          };
+
+          // 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 +365,28 @@ export class BunWorkerSandbox implements ISandbox {
                 });
               };
             }
-            // Freeze individual adapter to prevent method tampering
-            Object.freeze(adapterObj);
-            adaptersObj[adapterName] = adapterObj;
+
+            // Use Proxy to intercept undefined method calls
+            const adapterProxy = new Proxy(methodsImpl, {
+              get(target, prop) {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'symbol') return undefined;
+                const similar = findSimilar(String(prop), methods);
+                const suggestion = similar.length > 0
+                  ? '. Did you mean: ' + similar.join(', ') + '?'
+                  : '. Available: ' + methods.slice(0, 5).join(', ') + (methods.length > 5 ? '...' : '');
+                throw new Error(adapterName + '.' + String(prop) + ' 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,

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;
 }