@walkeros/mcp 3.0.2 → 3.1.0

package/dist/index.js

@@ -14,7 +14,7 @@ import { z } from "zod";
 var ValidateOutputShape = {
   valid: z.boolean().describe("Whether validation passed"),
   type: z.union([
-    z.enum(["contract", "event", "flow", "mapping"]),
+    z.enum(["contract", "entry", "event", "flow", "mapping"]),
     z.string().regex(/^(destinations|sources|transformers)\.\w+$/)
   ]).describe("What was validated"),
   errors: z.array(
@@ -56,15 +56,10 @@ var SimulateOutputShape = {
     z.object({
       received: z.boolean().describe("Whether destination received the event"),
       calls: z.number().describe("Number of API calls made"),
-      payload: z.unknown().optional().describe("Transformed payload sent")
+      payload: z.unknown().optional().describe("Full payload (only when verbose: true)")
     })
   ).optional().describe("Per-destination results"),
-  exampleMatch: z.object({
-    name: z.string(),
-    step: z.string(),
-    match: z.boolean(),
-    diff: z.string().optional()
-  }).optional().describe("Example comparison result when using example parameter"),
+  capturedEvents: z.array(z.record(z.string(), z.unknown())).optional().describe("Events captured by source simulation"),
   duration: z.number().optional().describe("Simulation duration in ms")
 };
 var PushOutputShape = {
@@ -85,60 +80,17 @@ var ExamplesListOutputShape = {
       hasIn: z.boolean().describe("Whether the example has an input value"),
       hasOut: z.boolean().describe("Whether the example has an output value"),
       hasMapping: z.boolean().describe("Whether the example has a mapping configuration"),
+      hasTrigger: z.boolean().describe("Whether the example has trigger metadata"),
       in: z.unknown().optional().describe("Input event data"),
       out: z.unknown().optional().describe("Expected output data"),
-      mapping: z.unknown().optional().describe("Mapping configuration for destinations")
+      mapping: z.unknown().optional().describe("Mapping configuration for destinations"),
+      trigger: z.object({
+        type: z.string().optional(),
+        options: z.unknown().optional()
+      }).optional().describe("Trigger metadata for source simulation")
     })
   ).describe("Step examples")
 };
-var PackageSearchOutputShape = {
-  package: z.string().describe("Package name"),
-  version: z.string().describe("Package version"),
-  description: z.string().optional().describe("Package description"),
-  type: z.string().optional().describe("Package type (destination, source, transformer)"),
-  platform: z.string().optional().describe("Target platform (web, server)"),
-  hintKeys: z.array(z.string()).describe("Available hint keys (use package_get section=hints to read)"),
-  exampleSummaries: z.array(
-    z.object({
-      name: z.string().describe("Example name"),
-      description: z.string().optional().describe("What this example shows")
-    })
-  ).describe(
-    "Step example names and descriptions (use package_get section=examples to read full content)"
-  )
-};
-var PackageSchemaOutputShape = {
-  package: z.string().describe("Package name"),
-  version: z.string().describe("Package version"),
-  type: z.string().describe("Package type (destination, source, transformer)"),
-  platform: z.string().describe("Target platform (web, server)"),
-  schemas: z.record(z.string(), z.unknown()).optional().describe("JSON Schemas for settings and mapping"),
-  examples: z.record(z.string(), z.unknown()).optional().describe(
-    "Full configuration examples (included when section=examples or section=all)"
-  ),
-  exampleSummaries: z.array(
-    z.object({
-      name: z.string().describe("Example name"),
-      description: z.string().optional().describe("What this example shows")
-    })
-  ).optional().describe(
-    "Example names and descriptions (included in default/summary mode)"
-  ),
-  hints: z.record(
-    z.string(),
-    z.object({
-      text: z.string(),
-      code: z.array(
-        z.object({
-          lang: z.string().optional(),
-          code: z.string()
-        })
-      ).optional()
-    })
-  ).optional().describe(
-    "Hints \u2014 text only in summary mode, with code blocks when section=hints or section=all"
-  )
-};
 
 // src/tools/validate.ts
 function registerFlowValidateTool(server2) {
@@ -270,6 +222,7 @@ function formatBytes(bytes) {
 }
 
 // src/tools/simulate.ts
+import { z as z3 } from "zod";
 import { simulate } from "@walkeros/cli";
 import { schemas as schemas3 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult3, mcpError as mcpError3 } from "@walkeros/core";
@@ -278,8 +231,17 @@ function registerFlowSimulateTool(server2) {
     "flow_simulate",
     {
       title: "Simulate Flow",
-      description: 'Simulate events through a walkerOS flow without making real API calls. Events must be in walkerOS event format (post-source output): { name: "entity action", data: {...} }. Use package_get on your source to check its output shape. Use the example parameter to load event input from a step example and compare output.',
-      inputSchema: schemas3.SimulateInputShape,
+      description: 'Simulate events through a walkerOS flow without making real API calls. For destinations: event is a walkerOS event { name: "entity action", data: {...} }. For sources: event is { content: ..., trigger?: { type?, options? }, env?: {...} }. Use step to target a specific step. Use flow_examples to discover available test data.',
+      inputSchema: {
+        configPath: schemas3.SimulateInputShape.configPath,
+        event: z3.union([z3.record(z3.string(), z3.unknown()), z3.string()]).optional().describe(
+          "For destinations: { name, data }. For sources: { content, trigger?, env? }. Can also be a JSON string or file path."
+        ),
+        flow: schemas3.SimulateInputShape.flow,
+        platform: schemas3.SimulateInputShape.platform,
+        step: schemas3.SimulateInputShape.step,
+        verbose: z3.boolean().optional().describe("Include full payload per destination (default: false)")
+      },
       outputSchema: SimulateOutputShape,
       annotations: {
         readOnlyHint: true,
@@ -288,26 +250,51 @@ function registerFlowSimulateTool(server2) {
         openWorldHint: false
       }
     },
-    async ({ configPath, event, flow, platform, example, step }) => {
+    async ({ configPath, event, flow, platform, step, verbose }) => {
       try {
-        if (!event && !example) {
-          throw new Error("Either event or example must be provided");
+        if (!event) {
+          throw new Error(
+            "event is required. For sources provide { content, trigger? }, for destinations provide { name, data }."
+          );
         }
         const raw = await simulate(configPath, event, {
           json: true,
           flow,
           platform,
-          example,
           step
         });
+        if (raw.capturedEvents) {
+          const eventCount = raw.capturedEvents.length;
+          const summary2 = `Source captured ${eventCount} event${eventCount !== 1 ? "s" : ""}`;
+          return mcpResult3(
+            {
+              success: raw.success,
+              error: raw.error,
+              summary: summary2,
+              capturedEvents: raw.capturedEvents,
+              duration: raw.duration
+            },
+            summary2,
+            {
+              next: eventCount > 0 ? [
+                "Use flow_simulate with a destination step to test downstream processing"
+              ] : [
+                "Check source package examples with package_get, verify trigger type matches"
+              ]
+            }
+          );
+        }
         const destinations = {};
         if (raw.usage) {
           for (const [name, calls] of Object.entries(raw.usage)) {
-            destinations[name] = {
+            const summary2 = {
               received: calls.length > 0,
-              calls: calls.length,
-              payload: calls.length > 0 ? calls[calls.length - 1] : void 0
+              calls: calls.length
             };
+            if (verbose && calls.length > 0) {
+              summary2.payload = calls[calls.length - 1];
+            }
+            destinations[name] = summary2;
           }
         }
         const destCount = Object.keys(destinations).length;
@@ -316,13 +303,11 @@ function registerFlowSimulateTool(server2) {
         ).length;
         const warnings = [];
         if (destCount === 0) {
-          warnings.push(
-            "No destinations found in flow configuration. Check that your flow defines at least one destination."
-          );
+          warnings.push("No destinations found in flow configuration.");
         }
         if (destCount > 0 && receivedCount === 0) {
           warnings.push(
-            "No destinations received the event. Check: mapping keys use nested entity\u2192action structure (not dot-separated), event name matches, consent is granted. Use package_get on the destination for mapping examples."
+            "No destinations received the event. Check: mapping keys use nested entity\u2192action structure, event name matches, consent is granted."
           );
         }
         const summary = `${receivedCount}/${destCount} destinations received the event`;
@@ -331,7 +316,6 @@ function registerFlowSimulateTool(server2) {
           error: raw.error,
           summary,
           destinations: destCount > 0 ? destinations : void 0,
-          exampleMatch: raw.exampleMatch,
           duration: raw.duration
         };
         return mcpResult3(result, summary, {
@@ -346,6 +330,7 @@ function registerFlowSimulateTool(server2) {
 }
 
 // src/tools/push.ts
+import { z as z4 } from "zod";
 import { push } from "@walkeros/cli";
 import { schemas as schemas4 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult4, mcpError as mcpError4 } from "@walkeros/core";
@@ -355,7 +340,14 @@ function registerFlowPushTool(server2) {
     {
       title: "Push Events",
       description: "Push a real event through a walkerOS flow to actual destinations. Makes real API calls to real endpoints. Best suited for server-side flows \u2014 web flows should use flow_simulate for testing.",
-      inputSchema: schemas4.PushInputShape,
+      inputSchema: {
+        configPath: schemas4.PushInputShape.configPath,
+        event: z4.record(z4.string(), z4.unknown()).describe(
+          'Event object, e.g. { name: "page view", data: { title: "Home" } }'
+        ),
+        flow: schemas4.PushInputShape.flow,
+        platform: schemas4.PushInputShape.platform
+      },
       outputSchema: PushOutputShape,
       annotations: {
         readOnlyHint: false,
@@ -390,7 +382,7 @@ function registerFlowPushTool(server2) {
 }
 
 // src/tools/examples.ts
-import { z as z3 } from "zod";
+import { z as z5 } from "zod";
 import { loadJsonConfig } from "@walkeros/cli";
 import { mcpResult as mcpResult5, mcpError as mcpError5 } from "@walkeros/core";
 function registerFlowExamplesTool(server2) {
@@ -400,10 +392,12 @@ function registerFlowExamplesTool(server2) {
       title: "Flow Examples",
       description: "List all step examples in a walkerOS flow configuration. Shows example names, step locations, and in/out shapes. Use this to discover available test fixtures and simulation data.",
       inputSchema: {
-        configPath: z3.string().min(1).describe("Path to flow configuration file"),
-        flow: z3.string().optional().describe("Flow name for multi-flow configs"),
-        step: z3.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
-        full: z3.boolean().optional().describe(
+        configPath: z5.string().min(1).describe(
+          "Path to flow configuration file, URL, or inline JSON string"
+        ),
+        flow: z5.string().optional().describe("Flow name for multi-flow configs"),
+        step: z5.string().optional().describe('Filter to a specific step (e.g., "destination.gtag")'),
+        full: z5.boolean().optional().describe(
           "Return full in/out/mapping data for each example (default: false, returns metadata only)"
         )
       },
@@ -451,7 +445,13 @@ function registerFlowExamplesTool(server2) {
                 hasIn: ex.in !== void 0,
                 hasOut: ex.out !== void 0,
                 hasMapping: ex.mapping !== void 0,
-                ...full ? { in: ex.in, out: ex.out, mapping: ex.mapping } : {}
+                hasTrigger: ex.trigger !== void 0,
+                ...full ? {
+                  in: ex.in,
+                  out: ex.out,
+                  mapping: ex.mapping,
+                  trigger: ex.trigger
+                } : {}
               });
             }
           }
@@ -465,7 +465,7 @@ function registerFlowExamplesTool(server2) {
         const totalExamples = examples.length;
         const summary = `${totalExamples} examples across ${stepSet.size} steps`;
         const hints = {
-          next: ["Use flow_simulate with example parameter to test"]
+          next: ["Use flow_simulate with step and event to simulate"]
         };
         if (totalExamples === 0) {
           hints.warnings = [
@@ -481,207 +481,85 @@ function registerFlowExamplesTool(server2) {
 }
 
 // src/tools/package.ts
-import { z as z4 } from "zod";
-import { fetchPackage, mcpResult as mcpResult6, mcpError as mcpError6 } from "@walkeros/core";
+import { z as z6 } from "zod";
+import {
+  fetchPackage,
+  mergeConfigSchema,
+  mcpResult as mcpResult6,
+  mcpError as mcpError6
+} from "@walkeros/core";
 
-// src/registry.ts
-var PACKAGE_REGISTRY = [
-  // Web Destinations
-  {
-    name: "@walkeros/web-destination-gtag",
-    type: "destination",
-    platform: "web",
-    description: "Google destination (GA4, Ads, GTM via gtag.js)"
-  },
-  {
-    name: "@walkeros/web-destination-meta",
-    type: "destination",
-    platform: "web",
-    description: "Meta (Facebook) Pixel"
-  },
-  {
-    name: "@walkeros/web-destination-plausible",
-    type: "destination",
-    platform: "web",
-    description: "Plausible Analytics"
-  },
-  {
-    name: "@walkeros/web-destination-snowplow",
-    type: "destination",
-    platform: "web",
-    description: "Snowplow Analytics"
-  },
-  {
-    name: "@walkeros/web-destination-piwikpro",
-    type: "destination",
-    platform: "web",
-    description: "Piwik PRO Analytics"
-  },
-  {
-    name: "@walkeros/web-destination-api",
-    type: "destination",
-    platform: "web",
-    description: "Generic HTTP API destination"
-  },
-  // Server Destinations
-  {
-    name: "@walkeros/server-destination-gcp",
-    type: "destination",
-    platform: "server",
-    description: "Google Cloud Platform (BigQuery)"
-  },
-  {
-    name: "@walkeros/server-destination-aws",
-    type: "destination",
-    platform: "server",
-    description: "AWS (Firehose)"
-  },
-  {
-    name: "@walkeros/server-destination-meta",
-    type: "destination",
-    platform: "server",
-    description: "Meta Conversions API (server-side)"
-  },
-  {
-    name: "@walkeros/server-destination-api",
-    type: "destination",
-    platform: "server",
-    description: "Generic HTTP API destination (server)"
-  },
-  {
-    name: "@walkeros/server-destination-datamanager",
-    type: "destination",
-    platform: "server",
-    description: "Google Data Manager"
-  },
-  // Web Sources
-  {
-    name: "@walkeros/web-source-browser",
-    type: "source",
-    platform: "web",
-    description: "Browser DOM event capture (clicks, page views, forms)"
-  },
-  {
-    name: "@walkeros/web-source-datalayer",
-    type: "source",
-    platform: "web",
-    description: "Google Tag Manager dataLayer bridge"
-  },
-  {
-    name: "@walkeros/web-source-session",
-    type: "source",
-    platform: "web",
-    description: "Session tracking source"
-  },
-  // CMP Sources
-  {
-    name: "@walkeros/web-source-cmp-cookiefirst",
-    type: "source",
-    platform: "web",
-    description: "CookieFirst consent management"
-  },
-  {
-    name: "@walkeros/web-source-cmp-cookiepro",
-    type: "source",
-    platform: "web",
-    description: "CookiePro/OneTrust consent management"
-  },
-  {
-    name: "@walkeros/web-source-cmp-usercentrics",
-    type: "source",
-    platform: "web",
-    description: "Usercentrics consent management"
-  },
-  // Server Sources
-  {
-    name: "@walkeros/server-source-express",
-    type: "source",
-    platform: "server",
-    description: "Express.js HTTP event endpoint"
-  },
-  {
-    name: "@walkeros/server-source-fetch",
-    type: "source",
-    platform: "server",
-    description: "Web Fetch API source (Cloudflare, Vercel Edge, Deno, Bun)"
-  },
-  {
-    name: "@walkeros/server-source-aws",
-    type: "source",
-    platform: "server",
-    description: "AWS sources (Lambda, API Gateway, Function URLs)"
-  },
-  {
-    name: "@walkeros/server-source-gcp",
-    type: "source",
-    platform: "server",
-    description: "GCP sources (Cloud Functions)"
-  },
-  // Transformers
-  {
-    name: "@walkeros/transformer-router",
-    type: "transformer",
-    platform: "universal",
-    description: "Route events to different destination subsets"
-  },
-  {
-    name: "@walkeros/transformer-validator",
-    type: "transformer",
-    platform: "universal",
-    description: "Event validation using JSON Schema"
-  },
-  {
-    name: "@walkeros/server-transformer-fingerprint",
-    type: "transformer",
-    platform: "server",
-    description: "Device fingerprinting for anonymous user identification"
-  },
-  {
-    name: "@walkeros/server-transformer-cache",
-    type: "transformer",
-    platform: "server",
-    description: "HTTP response caching with LRU eviction"
-  },
-  {
-    name: "@walkeros/server-transformer-file",
-    type: "transformer",
-    platform: "server",
-    description: "File serving transformer for static files"
-  },
-  // Stores
-  {
-    name: "@walkeros/store-memory",
-    type: "store",
-    platform: "universal",
-    description: "In-memory key-value store with LRU eviction and TTL"
-  },
-  {
-    name: "@walkeros/server-store-fs",
-    type: "store",
-    platform: "server",
-    description: "File system key-value store"
-  },
-  {
-    name: "@walkeros/server-store-s3",
-    type: "store",
-    platform: "server",
-    description: "AWS S3 key-value store"
-  },
-  {
-    name: "@walkeros/server-store-gcs",
-    type: "store",
-    platform: "server",
-    description: "Google Cloud Storage key-value store"
+// src/catalog.ts
+var NPM_SEARCH_URL = "https://registry.npmjs.org/-/v1/search";
+var JSDELIVR_BASE = "https://cdn.jsdelivr.net/npm";
+var WALKEROS_JSON_PATH = "dist/walkerOS.json";
+var CACHE_TTL = 5 * 60 * 1e3;
+var cache;
+function normalizePlatform(platform) {
+  if (platform == null) return [];
+  if (typeof platform === "string") {
+    return platform === "universal" ? ["web", "server"] : [platform];
   }
-];
-function filterRegistry(filters) {
-  let results = PACKAGE_REGISTRY;
+  if (Array.isArray(platform)) {
+    return platform.filter((v) => typeof v === "string");
+  }
+  return [];
+}
+async function fetchCatalog(filters) {
+  if (cache && Date.now() - cache.timestamp < CACHE_TTL) {
+    return applyFilters(cache.entries, filters);
+  }
+  let entries;
+  try {
+    entries = await fetchFromNpm();
+  } catch {
+    return [];
+  }
+  cache = { entries, timestamp: Date.now() };
+  return applyFilters(entries, filters);
+}
+async function fetchFromNpm() {
+  const res = await fetch(`${NPM_SEARCH_URL}?text=@walkeros/&size=250`, {
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!res.ok) throw new Error(`npm search failed: ${res.status}`);
+  const data = await res.json();
+  const metaResults = await Promise.allSettled(
+    data.objects.map((obj) => enrichWithMeta(obj.package))
+  );
+  return metaResults.filter(
+    (r) => r.status === "fulfilled"
+  ).map((r) => r.value).filter((entry) => entry !== void 0);
+}
+async function enrichWithMeta(pkg) {
+  try {
+    const res = await fetch(
+      `${JSDELIVR_BASE}/${pkg.name}@${pkg.version}/${WALKEROS_JSON_PATH}`,
+      { signal: AbortSignal.timeout(5e3) }
+    );
+    if (!res.ok) return void 0;
+    const json = await res.json();
+    const meta = json.$meta;
+    if (!meta || typeof meta.type !== "string") return void 0;
+    return {
+      name: pkg.name,
+      version: pkg.version,
+      description: pkg.description,
+      type: meta.type,
+      platform: normalizePlatform(meta.platform)
+    };
+  } catch {
+    return void 0;
+  }
+}
+function applyFilters(entries, filters) {
+  let results = entries;
   if (filters?.type) {
-    results = results.filter((p) => p.type === filters.type);
+    results = results.filter((e) => e.type === filters.type);
   }
   if (filters?.platform) {
     results = results.filter(
-      (p) => p.platform === filters.platform || p.platform === "universal"
+      (e) => e.platform.length === 0 || e.platform.includes(filters.platform)
     );
   }
   return results;
@@ -695,14 +573,14 @@ function registerPackageSearchTool(server2) {
       title: "Search Package",
       description: "Browse walkerOS packages or look up a specific one. Without package name: returns catalog filtered by type/platform. With package name: returns metadata, hint keys, and example summaries.",
       inputSchema: {
-        package: z4.string().min(1).optional().describe(
+        package: z6.string().min(1).optional().describe(
           "Exact npm package name for detailed lookup (e.g., @walkeros/web-destination-snowplow)"
         ),
-        type: z4.enum(["source", "destination", "transformer", "store"]).optional().describe("Filter by package type (browse mode)"),
-        platform: z4.enum(["web", "server"]).optional().describe(
+        type: z6.enum(["source", "destination", "transformer", "store"]).optional().describe("Filter by package type (browse mode)"),
+        platform: z6.enum(["web", "server"]).optional().describe(
           "Filter by platform (browse mode, includes universal packages)"
         ),
-        version: z4.string().optional().describe("Package version for detailed lookup (default: latest)")
+        version: z6.string().optional().describe("Package version for detailed lookup (default: latest)")
       },
       // No outputSchema: browse mode returns {catalog, count}, lookup returns metadata — incompatible shapes
       annotations: {
@@ -714,7 +592,7 @@ function registerPackageSearchTool(server2) {
     },
     async ({ package: packageName, type, platform, version }) => {
       if (!packageName) {
-        const catalog = filterRegistry({ type, platform });
+        const catalog = await fetchCatalog({ type, platform });
         const result = { catalog, count: catalog.length };
         const summary = `${catalog.length} packages found`;
         return mcpResult6(result, summary, {
@@ -728,7 +606,7 @@ function registerPackageSearchTool(server2) {
           version: info.version,
           description: info.description,
           type: info.type,
-          platform: info.platform,
+          platform: normalizePlatform(info.platform),
           hintKeys: info.hintKeys,
           exampleSummaries: info.exampleSummaries
         };
@@ -752,15 +630,15 @@ function registerGetPackageSchemaTool(server2) {
       title: "Get Package",
       description: 'Fetch walkerOS package details from npm. By default returns schemas + hint texts + example summaries (lightweight). Use section parameter to get full content: "hints" (with code blocks), "examples" (full in/out data), or "all" (everything). Use package_search first to browse available packages.',
       inputSchema: {
-        package: z4.string().min(1).describe(
+        package: z6.string().min(1).describe(
           "Exact npm package name (e.g., @walkeros/web-destination-snowplow)"
         ),
-        version: z4.string().optional().describe("Package version (default: latest)"),
-        section: z4.enum(["hints", "examples", "all"]).optional().describe(
+        version: z6.string().optional().describe("Package version (default: latest)"),
+        section: z6.enum(["hints", "examples", "all"]).optional().describe(
           "Section to expand with full content. Default: summary view with schemas + hint texts + example descriptions"
         )
       },
-      outputSchema: PackageSchemaOutputShape,
+      // No outputSchema — removed to avoid SDK -32602 crashes on unexpected field values
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -771,12 +649,24 @@ function registerGetPackageSchemaTool(server2) {
     async ({ package: packageName, version, section }) => {
       try {
         const info = await fetchPackage(packageName, { version });
+        const mergedSchemas = {};
+        if (info.type) {
+          mergedSchemas.config = mergeConfigSchema(
+            info.type,
+            info.schemas
+          );
+        }
+        for (const [key, value] of Object.entries(info.schemas)) {
+          if (key !== "settings") {
+            mergedSchemas[key] = value;
+          }
+        }
         const result = {
           package: info.packageName,
           version: info.version,
           type: info.type,
-          platform: info.platform,
-          schemas: info.schemas
+          platform: normalizePlatform(info.platform),
+          schemas: mergedSchemas
         };
         if (info.hints) {
           if (section === "hints" || section === "all") {
@@ -810,7 +700,7 @@ function registerGetPackageSchemaTool(server2) {
 }
 
 // src/tools/flow-load.ts
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
 import { mcpResult as mcpResult7, mcpError as mcpError7 } from "@walkeros/core";
 var WEB_SKELETON = {
@@ -842,16 +732,16 @@ function registerFlowLoadTool(server2) {
       title: "Load or Create Flow",
       description: "Load an existing flow configuration from a local file path, URL, or walkerOS API (by flow ID). Or create a new empty flow by specifying a platform (web or server). Use the add-step prompt to add sources, destinations, transformers, or stores to the flow.",
       inputSchema: {
-        source: z5.string().optional().describe(
-          "Flow source: local file path (./flow.json), URL (https://...), or API flow ID (cfg_...). Omit to create a new flow."
+        source: z7.string().optional().describe(
+          "Flow source: local file path (./flow.json), URL (https://...), inline JSON string, or API flow ID (cfg_...). Omit to create a new flow."
         ),
-        platform: z5.enum(["web", "server"]).optional().describe(
+        platform: z7.enum(["web", "server"]).optional().describe(
           "Platform for new flows. Required when source is omitted. web = browser tracking, server = Node.js HTTP."
         )
       },
       outputSchema: {
-        version: z5.number().describe("Flow config version"),
-        flows: z5.record(z5.string(), z5.unknown()).describe("Flow definitions")
+        version: z7.number().describe("Flow config version"),
+        flows: z7.record(z7.string(), z7.unknown()).describe("Flow definitions")
       },
       annotations: {
         readOnlyHint: true,
@@ -907,7 +797,7 @@ function registerFlowLoadTool(server2) {
 }
 
 // src/tools/feedback.ts
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 import { feedback, readConfig, writeConfig } from "@walkeros/cli";
 import { mcpResult as mcpResult8, mcpError as mcpError8 } from "@walkeros/core";
 function registerFeedbackTool(server2) {
@@ -917,8 +807,8 @@ function registerFeedbackTool(server2) {
       title: "Send Feedback",
       description: "Send feedback about walkerOS",
       inputSchema: {
-        text: z6.string().describe("Your feedback text"),
-        anonymous: z6.boolean().optional().describe(
+        text: z8.string().describe("Your feedback text"),
+        anonymous: z8.boolean().optional().describe(
           "Include user/project info? false = include, true = anonymous. Only needed on first call if not yet configured."
         )
       },
@@ -952,7 +842,7 @@ function registerFeedbackTool(server2) {
           writeConfig({ ...base, anonymousFeedback: anonymous });
         }
         const isAnonymous = explicitAnonymous ?? anonymous ?? true;
-        await feedback(text, { anonymous: isAnonymous });
+        await feedback(text, { anonymous: isAnonymous, version: "3.1.0" });
         return mcpResult8({ ok: true }, "Feedback sent. Thanks!");
       } catch (error) {
         return mcpError8(error);
@@ -962,7 +852,7 @@ function registerFeedbackTool(server2) {
 }
 
 // src/tools/api.ts
-import { z as z8 } from "zod";
+import { z as z10 } from "zod";
 import {
   whoami,
   listProjects,
@@ -986,11 +876,11 @@ import {
 import { mcpResult as mcpResult9, mcpError as mcpError9 } from "@walkeros/core";
 
 // src/schemas/api-output.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 var ApiOutputShape = {
-  action: z7.string().describe("Action that was executed"),
-  ok: z7.boolean().describe("Whether the action succeeded"),
-  data: z7.unknown().describe("Action-specific result data")
+  action: z9.string().describe("Action that was executed"),
+  ok: z9.boolean().describe("Whether the action succeeded"),
+  data: z9.unknown().describe("Action-specific result data")
 };
 
 // src/tools/api.ts
@@ -1018,21 +908,26 @@ function registerApiTool(server2) {
     "api",
     {
       title: "walkerOS Cloud API",
-      description: "Manage walkerOS cloud projects, flows, and deployments. Requires WALKEROS_TOKEN env var.\n\nActions:\n- whoami \u2014 verify token, get user info\n- project.list/get/create/update/delete \u2014 manage projects\n- flow.list/get/create/update/delete/duplicate \u2014 manage flow configs\n- deploy \u2014 deploy a flow (auto-detects web/server)\n- deployment.get/list/create/delete \u2014 manage deployments\n\nParameters vary by action. id = flowId/projectId/slug depending on context. content = Flow.Config JSON for flow.create/update.",
+      description: "Manage walkerOS cloud projects, flows, and deployments. Requires WALKEROS_TOKEN env var.\n\nActions:\n- whoami \u2014 verify token, get user info\n- project.list/get/create/update/delete \u2014 manage projects\n- flow.list/get/create/update/delete/duplicate \u2014 manage flow configs\n- deploy \u2014 deploy a flow (auto-detects web/server)\n- deployment.get/list/create/delete \u2014 manage deployments\n\nParameters vary by action. content = Flow.Config JSON for flow.create/update.",
       inputSchema: {
-        action: z8.enum(ACTIONS).describe("API action to perform"),
-        id: z8.string().optional().describe("Resource ID (flowId, projectId, or deployment slug)"),
-        name: z8.string().optional().describe("Name for create/update operations"),
-        content: z8.record(z8.string(), z8.unknown()).optional().describe("Flow.Config JSON for flow operations"),
-        patch: z8.boolean().optional().describe("Use merge-patch for flow.update (default: true)"),
-        wait: z8.boolean().optional().describe("Wait for deploy to complete (default: true)"),
-        flowName: z8.string().optional().describe("Flow name for multi-settings flows"),
-        fields: z8.array(z8.string()).optional().describe("Dot-path field selectors for flow.get"),
-        type: z8.enum(["web", "server"]).optional().describe("Deployment type for deployment.create"),
-        sort: z8.string().optional().describe("Sort field for list operations"),
-        order: z8.enum(["asc", "desc"]).optional().describe("Sort order"),
-        status: z8.string().optional().describe("Status filter for deployment.list"),
-        includeDeleted: z8.boolean().optional().describe("Include deleted items in lists")
+        action: z10.enum(ACTIONS).describe("API action to perform"),
+        projectId: z10.string().optional().describe(
+          "Project ID (proj_...). Required for: project.get/update/delete, flow.create, flow.list. Falls back to WALKEROS_PROJECT_ID env var."
+        ),
+        flowId: z10.string().optional().describe(
+          "Flow ID (flow_...) or config ID (cfg_...). Required for: flow.get, flow.update, flow.delete, flow.duplicate, deploy. For deployment.get/delete: can be a deployment slug."
+        ),
+        name: z10.string().optional().describe("Name for create/update operations"),
+        content: z10.record(z10.string(), z10.unknown()).optional().describe("Flow.Config JSON for flow operations"),
+        patch: z10.boolean().optional().describe("Use merge-patch for flow.update (default: true)"),
+        wait: z10.boolean().optional().describe("Wait for deploy to complete (default: true)"),
+        flowName: z10.string().optional().describe("Flow name for multi-settings flows"),
+        fields: z10.array(z10.string()).optional().describe("Dot-path field selectors for flow.get"),
+        type: z10.enum(["web", "server"]).optional().describe("Deployment type for deployment.create"),
+        sort: z10.string().optional().describe("Sort field for list operations"),
+        order: z10.enum(["asc", "desc"]).optional().describe("Sort order"),
+        status: z10.string().optional().describe("Status filter for deployment.list"),
+        includeDeleted: z10.boolean().optional().describe("Include deleted items in lists")
       },
       outputSchema: ApiOutputShape,
       annotations: {
@@ -1045,7 +940,8 @@ function registerApiTool(server2) {
     async (params, extra) => {
       const {
         action,
-        id,
+        projectId,
+        flowId,
         name,
         content,
         patch,
@@ -1075,7 +971,7 @@ function registerApiTool(server2) {
             break;
           }
           case "project.get": {
-            data = await getProject({ projectId: id });
+            data = await getProject({ projectId });
             summary = `Project "${data.name}"`;
             break;
           }
@@ -1087,19 +983,19 @@ function registerApiTool(server2) {
           }
           case "project.update": {
             if (!name) throw new Error("name required for project.update");
-            data = await updateProject({ projectId: id, name });
+            data = await updateProject({ projectId, name });
             summary = `Updated project "${name}"`;
             break;
           }
           case "project.delete": {
-            data = await deleteProject({ projectId: id });
-            summary = `Deleted project ${id ?? "default"}`;
+            data = await deleteProject({ projectId });
+            summary = `Deleted project ${projectId ?? "default"}`;
             break;
           }
           // Flows
           case "flow.list": {
             data = await listFlows({
-              projectId: id,
+              projectId,
               sort,
               order,
               includeDeleted
@@ -1108,70 +1004,97 @@ function registerApiTool(server2) {
             break;
           }
           case "flow.get": {
-            if (!id) throw new Error("id required for flow.get");
-            data = await getFlow({ flowId: id, fields });
-            summary = `Flow "${data.name}" (${id})`;
+            if (!flowId) throw new Error("flowId required for flow.get");
+            data = await getFlow({ flowId, projectId, fields });
+            summary = `Flow "${data.name}" (${flowId})`;
             break;
           }
           case "flow.create": {
             if (!name) throw new Error("name required for flow.create");
             if (!content) throw new Error("content required for flow.create");
-            data = await createFlow({ name, content });
+            data = await createFlow({ name, content, projectId });
             summary = `Created flow "${name}" (${data.id})`;
             break;
           }
           case "flow.update": {
-            if (!id) throw new Error("id required for flow.update");
+            if (!flowId) throw new Error("flowId required for flow.update");
             data = await updateFlow({
-              flowId: id,
+              flowId,
               name,
               content,
+              projectId,
               mergePatch: patch ?? true
             });
-            summary = `Updated flow ${id}`;
+            summary = `Updated flow ${flowId}`;
             break;
           }
           case "flow.delete": {
-            if (!id) throw new Error("id required for flow.delete");
-            data = await deleteFlow({ flowId: id });
-            summary = `Deleted flow ${id}`;
+            if (!flowId) throw new Error("flowId required for flow.delete");
+            data = await deleteFlow({ flowId, projectId });
+            summary = `Deleted flow ${flowId}`;
             break;
           }
           case "flow.duplicate": {
-            if (!id) throw new Error("id required for flow.duplicate");
-            data = await duplicateFlow({ flowId: id, name });
-            summary = `Duplicated flow ${id}`;
+            if (!flowId) throw new Error("flowId required for flow.duplicate");
+            data = await duplicateFlow({ flowId, name, projectId });
+            summary = `Duplicated flow ${flowId}`;
             break;
           }
           // Deploy
           case "deploy": {
-            if (!id) throw new Error("id (flowId) required for deploy");
+            if (!flowId) throw new Error("flowId required for deploy");
             const progressToken = extra._meta?.progressToken;
+            const DEPLOY_TIMEOUT_MS = 9e4;
+            const timeoutSignal = AbortSignal.timeout(DEPLOY_TIMEOUT_MS);
+            const combinedAbort = new AbortController();
+            const onAbort = () => combinedAbort.abort();
+            timeoutSignal.addEventListener("abort", onAbort);
+            extra.signal?.addEventListener("abort", onAbort);
             data = await deploy({
-              flowId: id,
+              flowId,
+              projectId,
               wait: wait ?? true,
               flowName,
+              timeout: DEPLOY_TIMEOUT_MS,
               onStatus: (s, sub) => {
                 if (!progressToken) return;
+                const key = sub ? `${s}:${sub}` : s;
                 const stages = {
-                  bundling: 15,
-                  deploying: 55,
-                  published: 100,
-                  active: 100,
-                  failed: 100
+                  "bundling:building": {
+                    progress: 20,
+                    label: "Building bundle..."
+                  },
+                  "deploying:publishing": {
+                    progress: 60,
+                    label: "Publishing to CDN..."
+                  },
+                  "deploying:provisioning": {
+                    progress: 60,
+                    label: "Provisioning container..."
+                  },
+                  "deploying:starting": {
+                    progress: 80,
+                    label: "Starting container..."
+                  },
+                  published: { progress: 100, label: "Published" },
+                  active: { progress: 100, label: "Active" },
+                  failed: { progress: 100, label: "Failed" }
                 };
+                const stage = stages[key] ?? stages[s] ?? { progress: 10, label: key };
                 extra.sendNotification({
                   method: "notifications/progress",
                   params: {
                     progressToken,
-                    progress: stages[s] ?? 0,
+                    progress: stage.progress,
                     total: 100,
-                    message: sub ? `${s}:${sub}` : s
+                    message: stage.label
                   }
                 });
               },
-              signal: extra.signal
+              signal: combinedAbort.signal
             });
+            timeoutSignal.removeEventListener("abort", onAbort);
+            extra.signal?.removeEventListener("abort", onAbort);
             const st = data.status;
             const deployData = data;
             if (st === "failed") {
@@ -1180,7 +1103,7 @@ function registerApiTool(server2) {
                 next: ["Run flow_validate to check your configuration"]
               });
             } else {
-              summary = `Deployed flow ${id} \u2014 status: ${st}`;
+              summary = `Deployed flow ${flowId} \u2014 status: ${st}`;
               const publicUrl = deployData.publicUrl;
               const containerUrl = deployData.containerUrl;
               const deployType = deployData.type;
@@ -1202,21 +1125,21 @@ function registerApiTool(server2) {
           }
           // Deployments
           case "deployment.get": {
-            if (!id)
+            if (!flowId)
               throw new Error(
-                "id (flowId or slug) required for deployment.get"
+                "flowId (flowId or slug) required for deployment.get"
               );
             try {
-              data = await getDeployment({ flowId: id, flowName });
+              data = await getDeployment({ flowId, flowName });
             } catch {
-              data = await getDeploymentBySlug({ slug: id });
+              data = await getDeploymentBySlug({ slug: flowId });
             }
-            summary = `Deployment ${data.slug ?? id} \u2014 ${data.status}`;
+            summary = `Deployment ${data.slug ?? flowId} \u2014 ${data.status}`;
             break;
           }
           case "deployment.list": {
             data = await listDeployments({
-              projectId: id,
+              projectId,
               type,
               status
             });
@@ -1228,15 +1151,15 @@ function registerApiTool(server2) {
               throw new Error(
                 "type (web/server) required for deployment.create"
               );
-            data = await createDep({ type, label: name, projectId: id });
+            data = await createDep({ type, label: name, projectId });
             summary = `Created ${type} deployment ${data.slug}`;
             break;
           }
           case "deployment.delete": {
-            if (!id)
-              throw new Error("id (slug) required for deployment.delete");
-            data = await deleteDep({ slug: id });
-            summary = `Deleted deployment ${id}`;
+            if (!flowId)
+              throw new Error("flowId (slug) required for deployment.delete");
+            data = await deleteDep({ slug: flowId });
+            summary = `Deleted deployment ${flowId}`;
             break;
           }
           default:
@@ -1247,6 +1170,22 @@ function registerApiTool(server2) {
         return mcpResult9({ action, ok: true, data }, summary);
       } catch (error) {
         const msg = error instanceof Error ? error.message : "";
+        const name2 = error instanceof Error ? error.name : "";
+        if (action === "deploy" && (name2 === "AbortError" || name2 === "TimeoutError" || msg.includes("abort"))) {
+          return mcpResult9(
+            {
+              action,
+              ok: true,
+              data: { status: "deploying", flowId }
+            },
+            `Deploy in progress (timed out waiting). Use deployment.list with projectId to check status.`,
+            {
+              next: [
+                'Use api(action: "deployment.list") to check current status'
+              ]
+            }
+          );
+        }
         if (msg.includes("401") || msg.includes("403") || msg.includes("Unauthorized"))
           return mcpError9(
             error,
@@ -1268,14 +1207,17 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { fetchPackageSchema } from "@walkeros/core";
 function registerPackageSchemaResources(server2) {
   const template = new ResourceTemplate("walkeros://schema/{packageName}", {
-    list: async () => ({
-      resources: PACKAGE_REGISTRY.map((pkg) => ({
-        uri: `walkeros://schema/${encodeURIComponent(pkg.name)}`,
-        name: pkg.name,
-        description: `Schema and examples for ${pkg.name}`,
-        mimeType: "application/json"
-      }))
-    })
+    list: async () => {
+      const catalog = await fetchCatalog();
+      return {
+        resources: catalog.map((pkg) => ({
+          uri: `walkeros://schema/${encodeURIComponent(pkg.name)}`,
+          name: pkg.name,
+          description: `Schema and examples for ${pkg.name}`,
+          mimeType: "application/json"
+        }))
+      };
+    }
   });
   server2.registerResource(
     "package-schema",
@@ -1517,30 +1459,33 @@ function registerReferenceResources(server2) {
       description: "Complete walkerOS package catalog \u2014 all sources, destinations, transformers, and stores",
       mimeType: "application/json"
     },
-    async () => ({
-      contents: [
-        {
-          uri: "walkeros://reference/packages",
-          text: JSON.stringify(PACKAGE_REGISTRY, null, 2),
-          mimeType: "application/json"
-        }
-      ]
-    })
+    async () => {
+      const catalog = await fetchCatalog();
+      return {
+        contents: [
+          {
+            uri: "walkeros://reference/packages",
+            text: JSON.stringify(catalog, null, 2),
+            mimeType: "application/json"
+          }
+        ]
+      };
+    }
   );
 }
 
 // src/prompts/add-step.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 function registerAddStepPrompt(server2) {
   server2.registerPrompt(
     "add-step",
     {
       description: "Add a source, destination, transformer, or store step to a flow configuration. Guides through package selection, config scaffolding, and wiring.",
       argsSchema: {
-        stepType: z9.string().optional().describe(
+        stepType: z11.string().optional().describe(
           "Type of step to add: source, destination, transformer, or store"
         ),
-        flowPath: z9.string().optional().describe("Path to the flow.json file to modify")
+        flowPath: z11.string().optional().describe("Path to the flow.json file to modify")
       }
     },
     async ({ stepType, flowPath }) => ({
@@ -1554,7 +1499,7 @@ function registerAddStepPrompt(server2) {
               "",
               "Follow these steps:",
               `1. ${stepType ? "" : "Ask what type of step (source, destination, transformer, store). Then "}Use package_search to browse available packages for the selected type and platform.`,
-              `2. Use package_get with section="hints" to read the selected package's configuration guidance.`,
+              `2. Use package_get to read the package's config schema (schemas.config contains the full config shape: base fields like consent/require/logger + package-specific settings). Use section="hints" for additional guidance.`,
               '3. Use package_get with section="examples" to see working configuration examples.',
               "4. Scaffold the step config using the package schemas \u2014 include required settings with placeholder values.",
               "5. Wire the step into the flow: add to packages section (with version if needed), connect via next/before chains if needed.",
@@ -1580,14 +1525,14 @@ function registerAddStepPrompt(server2) {
 }
 
 // src/prompts/setup-mapping.ts
-import { z as z10 } from "zod";
+import { z as z12 } from "zod";
 function registerSetupMappingPrompt(server2) {
   server2.registerPrompt(
     "setup-mapping",
     {
       description: "Set up event mapping for any step in a flow. Teaches mapping syntax and uses package examples as templates.",
       argsSchema: {
-        stepName: z10.string().optional().describe('Step name in the flow (e.g., "gtag", "meta", "express")')
+        stepName: z12.string().optional().describe('Step name in the flow (e.g., "gtag", "meta", "express")')
       }
     },
     async ({ stepName }) => ({
@@ -1619,14 +1564,14 @@ function registerSetupMappingPrompt(server2) {
 }
 
 // src/prompts/manage-contract.ts
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 function registerManageContractPrompt(server2) {
   server2.registerPrompt(
     "manage-contract",
     {
       description: "Create or update event contracts for a flow. Can generate contracts from existing mappings or scaffold mappings from contracts.",
       argsSchema: {
-        direction: z11.string().optional().describe(
+        direction: z13.string().optional().describe(
           'Direction: "from-mappings" (extract contract from existing mappings), "from-scratch" (create new contract), or "to-mappings" (scaffold mappings from contract)'
         )
       }
@@ -1664,14 +1609,14 @@ function registerManageContractPrompt(server2) {
 }
 
 // src/prompts/use-definitions.ts
-import { z as z12 } from "zod";
+import { z as z14 } from "zod";
 function registerUseDefinitionsPrompt(server2) {
   server2.registerPrompt(
     "use-definitions",
     {
       description: "Extract shared patterns into definitions and variables for DRY, environment-aware flow configurations.",
       argsSchema: {
-        flowPath: z12.string().optional().describe("Path to the flow.json file to analyze")
+        flowPath: z14.string().optional().describe("Path to the flow.json file to analyze")
       }
     },
     async ({ flowPath }) => ({
@@ -1715,7 +1660,7 @@ function registerUseDefinitionsPrompt(server2) {
 var server = new McpServer(
   {
     name: "walkeros-flow",
-    version: "3.0.2"
+    version: "3.1.0"
   },
   {
     instructions: `walkerOS is an open-source, privacy-first event data collection platform. Define event pipelines as code using JSON flow configurations.
@@ -1751,7 +1696,7 @@ Key rules:
 
 ## Getting Started
 
-1. \`flow_load({ platform: "web" })\` or \`flow_load({ source: "./flow.json" })\` \u2014 create or load a flow
+1. \`flow_load({ platform: "web" })\` or \`flow_load({ source: "./flow.json" })\` \u2014 create or load a flow (also accepts inline JSON strings or URLs)
 2. \`package_search({ type: "destination", platform: "web" })\` \u2014 discover available packages
 3. Use the \`add-step\` prompt to add sources, destinations, transformers, or stores
 4. Use the \`setup-mapping\` prompt to configure event transformations
@@ -1768,7 +1713,7 @@ Read these before constructing configs manually: \`walkeros://reference/flow-sch
 
 ## Key Concepts
 
-- **Steps** are sources, destinations, transformers, or stores \u2014 each backed by an npm package. Use \`package_search\` to browse, \`package_get\` for schemas and examples.
+- **Steps** are sources, destinations, transformers, or stores \u2014 each backed by an npm package. Use \`package_search\` to browse, \`package_get\` for schemas and examples. \`package_get\` returns \`schemas.config\` \u2014 a merged JSON Schema combining base config fields (consent, require, logger, mapping, etc.) with the package's typed settings. Non-config schemas (mapping rules, utility schemas) remain as sibling keys.
 - **Mapping** transforms events using data/map/loop/set/condition rules. Same syntax on sources and destinations. Mapping rules use NESTED entity \u2192 action keying: event name "product add" maps to \`{ "product": { "add": Rule } }\`. Wildcards: \`{ "*": { "view": Rule } }\`.
 - **Contracts** define event schemas using entity-action keying. Can generate FROM mappings or scaffold mappings FROM contracts.
 - **Variables** ($var, $env, $def, $code, $store) enable DRY, environment-aware config. Use the \`use-definitions\` prompt to extract shared patterns.