@walkeros/mcp 2.0.1 → 3.0.0

package/dist/index.js

@@ -4,23 +4,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/tools/bundle.ts
-import { z as z2 } from "zod";
-import { bundle, bundleRemote } from "@walkeros/cli";
+// src/tools/validate.ts
+import { validate } from "@walkeros/cli";
 import { schemas } from "@walkeros/cli/dev";
+import { mcpResult, mcpError } from "@walkeros/core";
 
 // src/schemas/output.ts
 import { z } from "zod";
-var timestamp = z.string().describe("ISO 8601 timestamp");
-var projectId = z.string().describe("Project ID (proj_...)");
-var flowId = z.string().describe("Flow ID (cfg_...)");
-var ErrorOutputShape = {
-  error: z.string().describe("Error message")
-};
 var ValidateOutputShape = {
   valid: z.boolean().describe("Whether validation passed"),
   type: z.union([
-    z.enum(["event", "flow", "mapping"]),
+    z.enum(["contract", "event", "flow", "mapping"]),
     z.string().regex(/^(destinations|sources|transformers)\.\w+$/)
   ]).describe("What was validated"),
   errors: z.array(
@@ -55,12 +49,23 @@ var BundleOutputShape = {
 };
 var SimulateOutputShape = {
   success: z.boolean().describe("Whether simulation succeeded"),
-  error: z.string().optional().describe("Error message if simulation failed"),
-  collector: z.unknown().optional().describe("Collector state after simulation"),
-  elbResult: z.unknown().optional().describe("Push result from the collector"),
-  logs: z.array(z.unknown()).optional().describe("Log entries from simulation"),
-  usage: z.record(z.string(), z.array(z.unknown())).optional().describe("API call usage per destination"),
-  duration: z.number().optional().describe("Simulation duration in milliseconds")
+  error: z.string().optional().describe("Error message if failed"),
+  summary: z.string().describe("One-line result summary"),
+  destinations: z.record(
+    z.string(),
+    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")
+    })
+  ).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"),
+  duration: z.number().optional().describe("Simulation duration in ms")
 };
 var PushOutputShape = {
   success: z.boolean().describe("Whether push succeeded"),
@@ -68,102 +73,142 @@ var PushOutputShape = {
   duration: z.number().describe("Push duration in milliseconds"),
   error: z.string().optional().describe("Error message if push failed")
 };
-var WhoamiOutputShape = {
-  userId: z.string().describe("User ID"),
-  email: z.string().describe("User email address"),
-  projectId: z.string().nullable().describe("Project ID if token is project-scoped")
-};
-var projectFields = {
-  id: projectId,
-  name: z.string().describe("Project name"),
-  role: z.enum(["owner", "member"]).describe("Your role in this project"),
-  createdAt: timestamp,
-  updatedAt: timestamp
-};
-var ProjectOutputShape = { ...projectFields };
-var ListProjectsOutputShape = {
-  projects: z.array(z.object(projectFields)).describe("List of projects"),
-  total: z.number().describe("Total number of projects")
-};
-var flowFields = {
-  id: flowId,
-  name: z.string().describe("Flow name"),
-  content: z.record(z.string(), z.unknown()).describe("Flow.Setup JSON content"),
-  createdAt: timestamp,
-  updatedAt: timestamp,
-  deletedAt: z.string().nullable().optional().describe("Deletion timestamp if soft-deleted")
-};
-var FlowOutputShape = { ...flowFields };
-var flowSummaryFields = {
-  id: flowId,
-  name: z.string().describe("Flow name"),
-  createdAt: timestamp,
-  updatedAt: timestamp,
-  deletedAt: z.string().nullable().describe("Deletion timestamp if soft-deleted")
-};
-var ListFlowsOutputShape = {
-  flows: z.array(z.object(flowSummaryFields)).describe("List of flow summaries"),
-  total: z.number().describe("Total number of flows")
+var ExamplesListOutputShape = {
+  flow: z.string().describe("Flow name"),
+  count: z.number().describe("Number of examples found"),
+  examples: z.array(
+    z.object({
+      step: z.string().describe('Step location (e.g., "destination.gtag")'),
+      stepType: z.enum(["source", "transformer", "destination"]).describe("Step type"),
+      stepName: z.string().describe("Step name"),
+      exampleName: z.string().describe("Example name"),
+      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"),
+      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")
+    })
+  ).describe("Step examples")
 };
-var DeleteOutputShape = {
-  success: z.literal(true).describe("Deletion succeeded")
+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()).describe("JSON Schemas for settings and mapping"),
-  examples: z.record(z.string(), z.unknown()).optional().describe("Configuration examples")
-};
-var BundleRemoteOutputShape = {
-  success: z.boolean().describe("Whether bundling succeeded"),
-  bundle: z.string().describe("Compiled JavaScript bundle"),
-  size: z.number().describe("Bundle size in bytes"),
-  stats: z.record(z.string(), z.unknown()).optional().describe("Bundle statistics from 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/helpers.ts
-function apiResult(result) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    structuredContent: result
-  };
-}
-function apiError(error) {
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({
-          error: error instanceof Error ? error.message : "Unknown error"
-        })
+// src/tools/validate.ts
+function registerFlowValidateTool(server2) {
+  server2.registerTool(
+    "flow_validate",
+    {
+      title: "Validate Flow",
+      description: "Validate walkerOS events, flow configurations, mapping rules, or data contracts. Accepts JSON strings, file paths, or URLs as input. Returns validation results with errors, warnings, and details.",
+      inputSchema: schemas.ValidateInputShape,
+      outputSchema: ValidateOutputShape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ type, input, flow, path }) => {
+      try {
+        const result = await validate(type, input, {
+          flow,
+          path
+        });
+        const summary = result.valid ? "Valid" : `Invalid: ${result.errors.length} errors, ${result.warnings.length} warnings`;
+        const hints = result.valid ? {
+          next: [
+            "Use flow_simulate to test event flow",
+            "Use flow_bundle to build"
+          ]
+        } : {
+          next: [
+            "Fix errors above, then run flow_validate again",
+            "Read walkeros://reference/flow-schema for correct structure"
+          ]
+        };
+        return mcpResult(result, summary, hints);
+      } catch (error) {
+        return mcpError(
+          error,
+          "Check the input parameter \u2014 expected a JSON string, file path, or URL"
+        );
       }
-    ],
-    isError: true
-  };
+    }
+  );
 }
 
 // src/tools/bundle.ts
-function registerBundleTool(server2) {
+import { z as z2 } from "zod";
+import { bundle, bundleRemote } from "@walkeros/cli";
+import { schemas as schemas2 } from "@walkeros/cli/dev";
+import { mcpResult as mcpResult2, mcpError as mcpError2 } from "@walkeros/core";
+function registerFlowBundleTool(server2) {
   server2.registerTool(
-    "bundle",
+    "flow_bundle",
     {
-      title: "Bundle",
+      title: "Bundle Flow",
       description: "Bundle a walkerOS flow configuration into deployable JavaScript. Resolves all destinations, sources, and transformers, then outputs a tree-shaken production bundle. Returns bundle statistics. Set remote: true to use the walkerOS cloud service instead of local build tools.",
       inputSchema: {
-        ...schemas.BundleInputShape,
+        ...schemas2.BundleInputShape,
         remote: z2.boolean().optional().describe(
           "Use remote cloud bundling (requires WALKEROS_TOKEN). Default: false (local)"
         ),
-        content: z2.record(z2.string(), z2.unknown()).optional().describe("Flow.Setup JSON content (required when remote: true)")
+        content: z2.record(z2.string(), z2.unknown()).optional().describe("Flow.Config JSON content (required when remote: true)")
       },
       outputSchema: BundleOutputShape,
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false
+        idempotentHint: false,
+        openWorldHint: true
       }
     },
     async ({ configPath, flow, stats, output, remote, content }) => {
@@ -175,54 +220,66 @@ function registerBundleTool(server2) {
             content,
             flowName: flow
           });
-          return apiResult({ success: true, ...result2 });
+          const r = result2;
+          const size2 = r.totalSize ?? r.size;
+          const time2 = r.buildTime;
+          const summary2 = `Bundled${size2 ? ` (${formatBytes(size2)}` : ""}${time2 ? `, ${time2}ms)` : size2 ? ")" : ""}`;
+          return mcpResult2({ success: true, ...result2 }, summary2, {
+            next: [
+              "Use flow_simulate to test",
+              "Use api({ action: 'deploy' }) to publish"
+            ]
+          });
         }
         const result = await bundle(configPath, {
           flowName: flow,
           stats: stats ?? true,
           buildOverrides: output ? { output } : void 0
         });
-        const output_ = result ?? {
-          success: true,
-          message: "Bundle created"
-        };
-        return {
-          content: [
+        if (!result) {
+          return mcpResult2(
+            { success: false, message: "Bundle produced no output" },
+            "Bundle produced no output",
             {
-              type: "text",
-              text: JSON.stringify(output_, null, 2)
+              warnings: [
+                "The build returned no result. The flow may be empty or misconfigured."
+              ],
+              next: ["Run flow_validate to check your configuration"]
             }
-          ],
-          structuredContent: output_
-        };
+          );
+        }
+        const output_ = result;
+        const size = output_.totalSize;
+        const time = output_.buildTime;
+        const summary = `Bundled${size ? ` (${formatBytes(size)}` : ""}${time ? `, ${time}ms)` : size ? ")" : ""}`;
+        return mcpResult2({ success: true, ...output_ }, summary, {
+          next: [
+            "Use flow_simulate to test",
+            "Use api({ action: 'deploy' }) to publish"
+          ]
+        });
       } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                success: false,
-                error: error instanceof Error ? error.message : "Unknown error"
-              })
-            }
-          ],
-          isError: true
-        };
+        return mcpError2(error, "Run flow_validate for detailed error messages");
       }
     }
   );
 }
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
 
 // src/tools/simulate.ts
 import { simulate } from "@walkeros/cli";
-import { schemas as schemas2 } from "@walkeros/cli/dev";
-function registerSimulateTool(server2) {
+import { schemas as schemas3 } from "@walkeros/cli/dev";
+import { mcpResult as mcpResult3, mcpError as mcpError3 } from "@walkeros/core";
+function registerFlowSimulateTool(server2) {
   server2.registerTool(
-    "simulate",
+    "flow_simulate",
     {
-      title: "Simulate",
-      description: "Simulate events through a walkerOS flow without making real API calls. Processes events through the full pipeline including transformers and destinations, returning detailed results with logs and usage statistics.",
-      inputSchema: schemas2.SimulateInputShape,
+      title: "Simulate Flow",
+      description: 'Simulate events through a walkerOS flow without making real API calls. Events must be in walkerOS format (post-source): { name: "entity action", data: {...} }. Raw source input (dataLayer pushes, HTTP requests) must first be converted to walkerOS events. Check source package examples to see what events a source outputs. Use the example parameter to load event input from a step example and compare output.',
+      inputSchema: schemas3.SimulateInputShape,
       outputSchema: SimulateOutputShape,
       annotations: {
         readOnlyHint: true,
@@ -231,42 +288,58 @@ function registerSimulateTool(server2) {
         openWorldHint: false
       }
     },
-    async ({ configPath, event, flow, platform }) => {
+    async ({ configPath, event, flow, platform, example, step }) => {
       try {
-        let parsedEvent = event;
-        if (event.startsWith("{") || event.startsWith("[")) {
-          try {
-            parsedEvent = JSON.parse(event);
-          } catch {
-          }
+        if (!event && !example) {
+          throw new Error("Either event or example must be provided");
         }
-        const result = await simulate(configPath, parsedEvent, {
+        const raw = await simulate(configPath, event, {
           json: true,
           flow,
-          platform
+          platform,
+          example,
+          step
         });
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ],
-          structuredContent: result
+        const destinations = {};
+        if (raw.usage) {
+          for (const [name, calls] of Object.entries(raw.usage)) {
+            destinations[name] = {
+              received: calls.length > 0,
+              calls: calls.length,
+              payload: calls.length > 0 ? calls[calls.length - 1] : void 0
+            };
+          }
+        }
+        const destCount = Object.keys(destinations).length;
+        const receivedCount = Object.values(destinations).filter(
+          (d) => d.received
+        ).length;
+        const warnings = [];
+        if (destCount === 0) {
+          warnings.push(
+            "No destinations found in flow configuration. Check that your flow defines at least one destination."
+          );
+        }
+        if (destCount > 0 && receivedCount === 0) {
+          warnings.push(
+            'No destinations received the event. Most common cause: mapping keys must be NESTED entity \u2192 action objects \u2014 event "product add" needs { "product": { "add": Rule } }, not "product.add". Also check event name match and consent settings.'
+          );
+        }
+        const summary = `${receivedCount}/${destCount} destinations received the event`;
+        const result = {
+          success: raw.success,
+          error: raw.error,
+          summary,
+          destinations: destCount > 0 ? destinations : void 0,
+          exampleMatch: raw.exampleMatch,
+          duration: raw.duration
         };
+        return mcpResult3(result, summary, {
+          next: ["Use flow_bundle to build for production"],
+          ...warnings.length > 0 ? { warnings } : {}
+        });
       } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                success: false,
-                error: error instanceof Error ? error.message : "Unknown error"
-              })
-            }
-          ],
-          isError: true
-        };
+        return mcpError3(error, "Run flow_validate for detailed error messages");
       }
     }
   );
@@ -274,14 +347,15 @@ function registerSimulateTool(server2) {
 
 // src/tools/push.ts
 import { push } from "@walkeros/cli";
-import { schemas as schemas3 } from "@walkeros/cli/dev";
-function registerPushTool(server2) {
+import { schemas as schemas4 } from "@walkeros/cli/dev";
+import { mcpResult as mcpResult4, mcpError as mcpError4 } from "@walkeros/core";
+function registerFlowPushTool(server2) {
   server2.registerTool(
-    "push",
+    "flow_push",
     {
-      title: "Push",
-      description: "Push a real event through a walkerOS flow to actual destinations. WARNING: This makes real API calls to real endpoints. Events will be sent to configured destinations (analytics, CRM, etc.).",
-      inputSchema: schemas3.PushInputShape,
+      title: "Push Events",
+      description: "Push a real event through a walkerOS flow to actual destinations. WARNING: This makes real API calls to real endpoints. Note: Web destinations (gtag, meta, etc.) require browser globals that are not available in Node.js. For web flows, use flow_simulate to test. flow_push works best for server-side flows.",
+      inputSchema: schemas4.PushInputShape,
       outputSchema: PushOutputShape,
       annotations: {
         readOnlyHint: false,
@@ -292,56 +366,48 @@ function registerPushTool(server2) {
     },
     async ({ configPath, event, flow, platform }) => {
       try {
-        let parsedEvent = event;
-        if (event.startsWith("{") || event.startsWith("[")) {
-          try {
-            parsedEvent = JSON.parse(event);
-          } catch {
-          }
-        }
-        const result = await push(configPath, parsedEvent, {
+        const result = await push(configPath, event, {
           json: true,
           flow,
           platform
         });
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ],
-          structuredContent: result
-        };
+        if (!result.success) {
+          return mcpError4(
+            new Error(result.error || "Push failed"),
+            "Check destination configuration and network connectivity. For web destinations, use flow_simulate instead."
+          );
+        }
+        const summary = `Pushed event${result.duration ? ` (${result.duration}ms)` : ""}`;
+        return mcpResult4(result, summary);
       } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                success: false,
-                error: error instanceof Error ? error.message : "Unknown error"
-              })
-            }
-          ],
-          isError: true
-        };
+        return mcpError4(
+          error,
+          "Check configPath and event format. For web destinations, use flow_simulate instead."
+        );
       }
     }
   );
 }
 
-// src/tools/validate.ts
-import { validate } from "@walkeros/cli";
-import { schemas as schemas4 } from "@walkeros/cli/dev";
-function registerValidateTool(server2) {
+// src/tools/examples.ts
+import { z as z3 } from "zod";
+import { loadJsonConfig } from "@walkeros/cli";
+import { mcpResult as mcpResult5, mcpError as mcpError5 } from "@walkeros/core";
+function registerFlowExamplesTool(server2) {
   server2.registerTool(
-    "validate",
+    "flow_examples",
     {
-      title: "Validate",
-      description: "Validate walkerOS events, flow configurations, or mapping rules. Accepts JSON strings, file paths, or URLs as input. Returns validation results with errors, warnings, and details.",
-      inputSchema: schemas4.ValidateInputShape,
-      outputSchema: ValidateOutputShape,
+      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(
+          "Return full in/out/mapping data for each example (default: false, returns metadata only)"
+        )
+      },
+      outputSchema: ExamplesListOutputShape,
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -349,111 +415,352 @@ function registerValidateTool(server2) {
         openWorldHint: false
       }
     },
-    async ({ type, input, flow }) => {
+    async ({ configPath, flow, step, full }) => {
       try {
-        let parsedInput = input;
-        if (input.startsWith("{") || input.startsWith("[")) {
-          try {
-            parsedInput = JSON.parse(input);
-          } catch {
-          }
+        const rawConfig = await loadJsonConfig(configPath);
+        const flowNames = Object.keys(rawConfig.flows || {});
+        const flowName = flow || (flowNames.length === 1 ? flowNames[0] : void 0);
+        if (!flowName) {
+          throw new Error(
+            `Multiple flows found. Specify flow parameter. Available: ${flowNames.join(", ")}`
+          );
         }
-        const result = await validate(type, parsedInput, { flow });
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
+        const flowSettings = rawConfig.flows[flowName];
+        if (!flowSettings) {
+          throw new Error(`Flow "${flowName}" not found`);
+        }
+        const examples = [];
+        const stepTypes = [
+          { key: "sources", type: "source" },
+          { key: "transformers", type: "transformer" },
+          { key: "destinations", type: "destination" }
+        ];
+        for (const { key, type } of stepTypes) {
+          const refs = flowSettings[key] || {};
+          for (const [name, ref] of Object.entries(refs)) {
+            if (!ref.examples) continue;
+            if (step && `${type}.${name}` !== step) continue;
+            for (const [exName, ex] of Object.entries(
+              ref.examples
+            )) {
+              examples.push({
+                step: `${type}.${name}`,
+                stepType: type,
+                stepName: name,
+                exampleName: exName,
+                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 } : {}
+              });
             }
-          ],
-          structuredContent: result
+          }
+        }
+        const stepSet = new Set(examples.map((e) => e.step));
+        const result = {
+          flow: flowName,
+          count: examples.length,
+          examples
         };
-      } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                valid: false,
-                error: error instanceof Error ? error.message : "Unknown error"
-              })
-            }
-          ],
-          isError: true
+        const totalExamples = examples.length;
+        const summary = `${totalExamples} examples across ${stepSet.size} steps`;
+        const hints = {
+          next: ["Use flow_simulate with example parameter to test"]
         };
+        if (totalExamples === 0) {
+          hints.warnings = [
+            "No examples found. Add examples to step definitions in your flow config for testing."
+          ];
+        }
+        return mcpResult5(result, summary, hints);
+      } catch (error) {
+        return mcpError5(error, "Check configPath \u2014 expected a flow.json file");
       }
     }
   );
 }
 
-// src/tools/auth.ts
-import { whoami } from "@walkeros/cli";
-function registerAuthTools(server2) {
-  server2.registerTool(
-    "whoami",
-    {
-      title: "Who Am I",
-      description: "Verify your API token and see your identity. Returns user ID, email, and project ID (if token is project-scoped). Use this to confirm your token works and discover your project ID.",
-      inputSchema: {},
-      outputSchema: WhoamiOutputShape,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true
-      }
-    },
-    async () => {
-      try {
-        return apiResult(await whoami());
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
+// src/tools/package.ts
+import { z as z4 } from "zod";
+import { fetchPackage, 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"
+  }
+];
+function filterRegistry(filters) {
+  let results = PACKAGE_REGISTRY;
+  if (filters?.type) {
+    results = results.filter((p) => p.type === filters.type);
+  }
+  if (filters?.platform) {
+    results = results.filter(
+      (p) => p.platform === filters.platform || p.platform === "universal"
+    );
+  }
+  return results;
 }
 
-// src/tools/projects.ts
-import { z as z3 } from "zod";
-import {
-  listProjects,
-  getProject,
-  createProject,
-  updateProject,
-  deleteProject
-} from "@walkeros/cli";
-function registerProjectTools(server2) {
+// src/tools/package.ts
+function registerPackageSearchTool(server2) {
   server2.registerTool(
-    "list-projects",
+    "package_search",
     {
-      title: "List Projects",
-      description: "List all projects you have access to. Returns project IDs, names, and your role.",
-      inputSchema: {},
-      outputSchema: ListProjectsOutputShape,
+      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(
+          "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(
+          "Filter by platform (browse mode, includes universal packages)"
+        ),
+        version: z4.string().optional().describe("Package version for detailed lookup (default: latest)")
+      },
+      // No outputSchema: browse mode returns {catalog, count}, lookup returns metadata — incompatible shapes
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
-        openWorldHint: true
+        openWorldHint: false
       }
     },
-    async () => {
+    async ({ package: packageName, type, platform, version }) => {
+      if (!packageName) {
+        const catalog = filterRegistry({ type, platform });
+        const result = { catalog, count: catalog.length };
+        const summary = `${catalog.length} packages found`;
+        return mcpResult6(result, summary, {
+          next: ["Use package_get for schemas and examples"]
+        });
+      }
       try {
-        return apiResult(await listProjects());
+        const info = await fetchPackage(packageName, { version });
+        const result = {
+          package: info.packageName,
+          version: info.version,
+          description: info.description,
+          type: info.type,
+          platform: info.platform,
+          hintKeys: info.hintKeys,
+          exampleSummaries: info.exampleSummaries
+        };
+        const summary = `${info.packageName} v${info.version}`;
+        return mcpResult6(result, summary, {
+          next: ["Use package_get for schemas and examples"]
+        });
       } catch (error) {
-        return apiError(error);
+        return mcpError6(
+          error,
+          "Package not found. Use package_search without parameters to browse available packages."
+        );
       }
     }
   );
+}
+function registerGetPackageSchemaTool(server2) {
   server2.registerTool(
-    "get-project",
+    "package_get",
     {
-      title: "Get Project",
-      description: "Get details for a project. Uses WALKEROS_PROJECT_ID if projectId is omitted.",
+      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: {
-        projectId: z3.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
+        package: z4.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(
+          "Section to expand with full content. Default: summary view with schemas + hint texts + example descriptions"
+        )
       },
-      outputSchema: ProjectOutputShape,
+      outputSchema: PackageSchemaOutputShape,
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -461,377 +768,441 @@ function registerProjectTools(server2) {
         openWorldHint: true
       }
     },
-    async ({ projectId: projectId2 }) => {
+    async ({ package: packageName, version, section }) => {
       try {
-        return apiResult(await getProject({ projectId: projectId2 }));
+        const info = await fetchPackage(packageName, { version });
+        const result = {
+          package: info.packageName,
+          version: info.version,
+          type: info.type,
+          platform: info.platform,
+          schemas: info.schemas
+        };
+        if (info.hints) {
+          if (section === "hints" || section === "all") {
+            result.hints = info.hints;
+          } else {
+            const hintSummary = {};
+            for (const [key, hint] of Object.entries(info.hints)) {
+              const h = hint;
+              hintSummary[key] = { text: h.text };
+            }
+            result.hints = hintSummary;
+          }
+        }
+        if (section === "examples" || section === "all") {
+          result.examples = info.examples;
+        } else {
+          result.exampleSummaries = info.exampleSummaries;
+        }
+        const schemaCount = Object.keys(info.schemas).length;
+        const exampleCount = info.exampleSummaries.length;
+        const summary = `${info.packageName} \u2014 ${schemaCount} schemas, ${exampleCount} examples`;
+        return mcpResult6(result, summary);
       } catch (error) {
-        return apiError(error);
+        return mcpError6(
+          error,
+          "Use package_search to browse available package names."
+        );
       }
     }
   );
-  server2.registerTool(
-    "create-project",
-    {
-      title: "Create Project",
-      description: "Create a new project.",
-      inputSchema: {
-        name: z3.string().min(1).max(255).describe("Project name")
-      },
-      outputSchema: ProjectOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ name }) => {
-      try {
-        return apiResult(await createProject({ name }));
-      } catch (error) {
-        return apiError(error);
-      }
+}
+
+// src/tools/flow-load.ts
+import { z as z5 } from "zod";
+import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
+import { mcpResult as mcpResult7, mcpError as mcpError7 } from "@walkeros/core";
+var WEB_SKELETON = {
+  version: 3,
+  flows: {
+    default: {
+      web: {},
+      packages: {},
+      sources: {},
+      destinations: {}
     }
-  );
-  server2.registerTool(
-    "update-project",
-    {
-      title: "Update Project",
-      description: "Update a project name. Uses WALKEROS_PROJECT_ID if projectId is omitted.",
-      inputSchema: {
-        projectId: z3.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)"),
-        name: z3.string().min(1).max(255).describe("New project name")
-      },
-      outputSchema: ProjectOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ projectId: projectId2, name }) => {
-      try {
-        return apiResult(await updateProject({ projectId: projectId2, name }));
-      } catch (error) {
-        return apiError(error);
-      }
+  }
+};
+var SERVER_SKELETON = {
+  version: 3,
+  flows: {
+    default: {
+      server: {},
+      packages: {},
+      sources: {},
+      destinations: {}
     }
-  );
+  }
+};
+function registerFlowLoadTool(server2) {
   server2.registerTool(
-    "delete-project",
+    "flow_load",
     {
-      title: "Delete Project",
-      description: "Soft-delete a project and all its flows. WARNING: This deletes the project and ALL associated flows and data. Uses WALKEROS_PROJECT_ID if projectId is omitted.",
+      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: {
-        projectId: z3.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
+        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."
+        ),
+        platform: z5.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")
       },
-      outputSchema: DeleteOutputShape,
       annotations: {
-        readOnlyHint: false,
-        destructiveHint: true,
-        idempotentHint: false,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
         openWorldHint: true
       }
     },
-    async ({ projectId: projectId2 }) => {
+    async ({ source, platform }) => {
       try {
-        return apiResult(await deleteProject({ projectId: projectId2 }));
+        if (source) {
+          const config = await loadJsonConfig2(source);
+          return mcpResult7(
+            config,
+            `Loaded flow from ${source}. Use flow_validate to check, or add-step prompt to modify.`,
+            {
+              next: [
+                "Use flow_validate to check",
+                "Use add-step prompt to modify"
+              ]
+            }
+          );
+        }
+        if (!platform) {
+          return mcpError7(
+            new Error(
+              "Provide source (file path, URL, or flow ID) to load existing flow, or platform (web/server) to create a new one."
+            )
+          );
+        }
+        const skeleton = platform === "web" ? WEB_SKELETON : SERVER_SKELETON;
+        return mcpResult7(
+          skeleton,
+          `Created empty ${platform} flow. Use the add-step prompt to add sources, destinations, and transformers.`,
+          {
+            next: [
+              "Read walkeros://reference/flow-schema for config structure",
+              "Use add-step prompt to add sources and destinations"
+            ]
+          }
+        );
       } catch (error) {
-        return apiError(error);
+        const msg = error instanceof Error ? error.message : "";
+        if (msg.includes("not found") || msg.includes("ENOENT"))
+          return mcpError7(
+            error,
+            "Check configPath \u2014 expected a flow.json file"
+          );
+        return mcpError7(error);
       }
     }
   );
 }
 
-// src/tools/flows.ts
-import { z as z4 } from "zod";
+// src/tools/api.ts
+import { z as z7 } from "zod";
 import {
+  whoami,
+  listProjects,
+  getProject,
+  createProject,
+  updateProject,
+  deleteProject,
   listFlows,
   getFlow,
   createFlow,
   updateFlow,
   deleteFlow,
-  duplicateFlow
+  duplicateFlow,
+  deploy,
+  getDeployment,
+  listDeployments,
+  getDeploymentBySlug,
+  createDeployment as createDep,
+  deleteDeployment as deleteDep
 } from "@walkeros/cli";
-function registerFlowTools(server2) {
-  server2.registerTool(
-    "list-flows",
-    {
-      title: "List Flows",
-      description: "List all flow configurations in a project.",
-      inputSchema: {
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)"),
-        sort: z4.enum(["name", "updated_at", "created_at"]).optional().describe("Sort field (default: updated_at)"),
-        order: z4.enum(["asc", "desc"]).optional().describe("Sort order (default: desc)"),
-        includeDeleted: z4.boolean().optional().describe("Include soft-deleted flows (default: false)")
-      },
-      outputSchema: ListFlowsOutputShape,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true
-      }
-    },
-    async ({ projectId: projectId2, sort, order, includeDeleted }) => {
-      try {
-        return apiResult(
-          await listFlows({ projectId: projectId2, sort, order, includeDeleted })
-        );
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
+import { mcpResult as mcpResult8, mcpError as mcpError8 } from "@walkeros/core";
+
+// src/schemas/api-output.ts
+import { z as z6 } from "zod";
+var ApiOutputShape = {
+  action: z6.string().describe("Action that was executed"),
+  ok: z6.boolean().describe("Whether the action succeeded"),
+  data: z6.unknown().describe("Action-specific result data")
+};
+
+// src/tools/api.ts
+var ACTIONS = [
+  "whoami",
+  "project.list",
+  "project.get",
+  "project.create",
+  "project.update",
+  "project.delete",
+  "flow.list",
+  "flow.get",
+  "flow.create",
+  "flow.update",
+  "flow.delete",
+  "flow.duplicate",
+  "deploy",
+  "deployment.get",
+  "deployment.list",
+  "deployment.create",
+  "deployment.delete"
+];
+function registerApiTool(server2) {
   server2.registerTool(
-    "get-flow",
+    "api",
     {
-      title: "Get Flow",
-      description: "Get a flow configuration with its full content (Flow.Setup JSON).",
+      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.",
       inputSchema: {
-        flowId: z4.string().describe("Flow ID (cfg_...)"),
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
+        action: z7.enum(ACTIONS).describe("API action to perform"),
+        id: z7.string().optional().describe("Resource ID (flowId, projectId, or deployment slug)"),
+        name: z7.string().optional().describe("Name for create/update operations"),
+        content: z7.record(z7.string(), z7.unknown()).optional().describe("Flow.Config JSON for flow operations"),
+        patch: z7.boolean().optional().describe("Use merge-patch for flow.update (default: true)"),
+        wait: z7.boolean().optional().describe("Wait for deploy to complete (default: true)"),
+        flowName: z7.string().optional().describe("Flow name for multi-settings flows"),
+        fields: z7.array(z7.string()).optional().describe("Dot-path field selectors for flow.get"),
+        type: z7.enum(["web", "server"]).optional().describe("Deployment type for deployment.create"),
+        sort: z7.string().optional().describe("Sort field for list operations"),
+        order: z7.enum(["asc", "desc"]).optional().describe("Sort order"),
+        status: z7.string().optional().describe("Status filter for deployment.list"),
+        includeDeleted: z7.boolean().optional().describe("Include deleted items in lists")
       },
-      outputSchema: FlowOutputShape,
+      outputSchema: ApiOutputShape,
       annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
         openWorldHint: true
       }
     },
-    async ({ flowId: flowId2, projectId: projectId2 }) => {
+    async (params, extra) => {
+      const {
+        action,
+        id,
+        name,
+        content,
+        patch,
+        wait,
+        flowName,
+        fields,
+        type,
+        sort,
+        order,
+        status,
+        includeDeleted
+      } = params;
       try {
-        return apiResult(await getFlow({ flowId: flowId2, projectId: projectId2 }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-  server2.registerTool(
-    "create-flow",
-    {
-      title: "Create Flow",
-      description: "Create a new flow configuration in a project.",
-      inputSchema: {
-        name: z4.string().min(1).max(255).describe("Flow name"),
-        content: z4.record(z4.string(), z4.unknown()).describe("Flow.Setup JSON content (must have version: 1)"),
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
-      },
-      outputSchema: FlowOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ name, content, projectId: projectId2 }) => {
-      try {
-        return apiResult(await createFlow({ name, content, projectId: projectId2 }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-  server2.registerTool(
-    "update-flow",
-    {
-      title: "Update Flow",
-      description: "Update a flow configuration name and/or content.",
-      inputSchema: {
-        flowId: z4.string().describe("Flow ID (cfg_...)"),
-        name: z4.string().min(1).max(255).optional().describe("New flow name"),
-        content: z4.record(z4.string(), z4.unknown()).optional().describe("New Flow.Setup JSON content"),
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
-      },
-      outputSchema: FlowOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ flowId: flowId2, name, content, projectId: projectId2 }) => {
-      try {
-        return apiResult(
-          await updateFlow({ flowId: flowId2, name, content, projectId: projectId2 })
-        );
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-  server2.registerTool(
-    "delete-flow",
-    {
-      title: "Delete Flow",
-      description: "Soft-delete a flow configuration. WARNING: This removes the flow configuration. Can be restored later. Requires flowId.",
-      inputSchema: {
-        flowId: z4.string().describe("Flow ID (cfg_...)"),
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
-      },
-      outputSchema: DeleteOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: true,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ flowId: flowId2, projectId: projectId2 }) => {
-      try {
-        return apiResult(await deleteFlow({ flowId: flowId2, projectId: projectId2 }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-  server2.registerTool(
-    "duplicate-flow",
-    {
-      title: "Duplicate Flow",
-      description: "Create a copy of an existing flow configuration.",
-      inputSchema: {
-        flowId: z4.string().describe("Flow ID to duplicate (cfg_...)"),
-        name: z4.string().optional().describe('Name for the copy (defaults to "Copy of ...")'),
-        projectId: z4.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)")
-      },
-      outputSchema: FlowOutputShape,
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ flowId: flowId2, name, projectId: projectId2 }) => {
-      try {
-        return apiResult(await duplicateFlow({ flowId: flowId2, name, projectId: projectId2 }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-}
-
-// src/tools/deploy.ts
-import { z as z5 } from "zod";
-import { deploy, getDeployment } from "@walkeros/cli";
-function registerDeployTools(server2) {
-  server2.registerTool(
-    "deploy-flow",
-    {
-      title: "Deploy Flow",
-      description: "Deploy a flow to walkerOS cloud. Auto-detects web (script hosting) or server (container) from the flow content. Returns deployment status, and for web deploys the public URL and script tag.",
-      inputSchema: {
-        flowId: z5.string().describe("Flow ID to deploy"),
-        projectId: z5.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)"),
-        wait: z5.boolean().optional().default(true).describe(
-          "Wait for deployment to complete (default: true). Set to false to return immediately after triggering."
-        ),
-        flowName: z5.string().optional().describe(
-          "Flow name for multi-config flows. Required when a flow has multiple configs."
-        )
-      },
-      annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true
-      }
-    },
-    async ({ flowId: flowId2, projectId: projectId2, wait, flowName }) => {
-      try {
-        return apiResult(await deploy({ flowId: flowId2, projectId: projectId2, wait, flowName }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-  server2.registerTool(
-    "get-deployment",
-    {
-      title: "Get Deployment",
-      description: "Get the latest deployment status for a flow. Returns deployment type, status, URLs, and error details.",
-      inputSchema: {
-        flowId: z5.string().describe("Flow ID to check"),
-        projectId: z5.string().optional().describe("Project ID (defaults to WALKEROS_PROJECT_ID)"),
-        flowName: z5.string().optional().describe(
-          "Flow name for multi-config flows. Required when a flow has multiple configs."
-        )
-      },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true
-      }
-    },
-    async ({ flowId: flowId2, projectId: projectId2, flowName }) => {
-      try {
-        return apiResult(await getDeployment({ flowId: flowId2, projectId: projectId2, flowName }));
-      } catch (error) {
-        return apiError(error);
-      }
-    }
-  );
-}
-
-// src/tools/get-package-schema.ts
-import { z as z6 } from "zod";
-import { fetchPackageSchema } from "@walkeros/core";
-function registerGetPackageSchemaTool(server2) {
-  server2.registerTool(
-    "get-package-schema",
-    {
-      title: "Get Package Schema",
-      description: "Fetch walkerOS package schemas and examples from npm via jsdelivr CDN. Returns JSON Schemas for settings and mapping configuration, plus examples. Use this to understand how to configure a destination, source, or transformer when building a flow.json.",
-      inputSchema: {
-        package: z6.string().min(1).describe(
-          "Exact npm package name (e.g., @walkeros/web-destination-snowplow)"
-        ),
-        version: z6.string().optional().describe("Package version (default: latest)")
-      },
-      outputSchema: PackageSchemaOutputShape,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true
-      }
-    },
-    async ({ package: packageName, version }) => {
-      try {
-        const info = await fetchPackageSchema(packageName, { version });
-        const result = {
-          package: info.packageName,
-          version: info.version,
-          type: info.type,
-          platform: info.platform,
-          schemas: info.schemas,
-          examples: info.examples
-        };
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result, null, 2) }
-          ],
-          structuredContent: result
-        };
-      } catch (error) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: error instanceof Error ? error.message : "Unknown error"
-              })
+        let data;
+        let summary;
+        switch (action) {
+          // Auth
+          case "whoami": {
+            data = await whoami();
+            summary = `Authenticated as ${data.email}`;
+            break;
+          }
+          // Projects
+          case "project.list": {
+            data = await listProjects();
+            summary = `${(data.projects ?? []).length} projects`;
+            break;
+          }
+          case "project.get": {
+            data = await getProject({ projectId: id });
+            summary = `Project "${data.name}"`;
+            break;
+          }
+          case "project.create": {
+            if (!name) throw new Error("name required for project.create");
+            data = await createProject({ name });
+            summary = `Created project "${name}"`;
+            break;
+          }
+          case "project.update": {
+            if (!name) throw new Error("name required for project.update");
+            data = await updateProject({ projectId: id, name });
+            summary = `Updated project "${name}"`;
+            break;
+          }
+          case "project.delete": {
+            data = await deleteProject({ projectId: id });
+            summary = `Deleted project ${id ?? "default"}`;
+            break;
+          }
+          // Flows
+          case "flow.list": {
+            data = await listFlows({
+              projectId: id,
+              sort,
+              order,
+              includeDeleted
+            });
+            summary = `${(data.flows ?? []).length} flows`;
+            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})`;
+            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 });
+            summary = `Created flow "${name}" (${data.id})`;
+            break;
+          }
+          case "flow.update": {
+            if (!id) throw new Error("id required for flow.update");
+            data = await updateFlow({
+              flowId: id,
+              name,
+              content,
+              mergePatch: patch ?? true
+            });
+            summary = `Updated flow ${id}`;
+            break;
+          }
+          case "flow.delete": {
+            if (!id) throw new Error("id required for flow.delete");
+            data = await deleteFlow({ flowId: id });
+            summary = `Deleted flow ${id}`;
+            break;
+          }
+          case "flow.duplicate": {
+            if (!id) throw new Error("id required for flow.duplicate");
+            data = await duplicateFlow({ flowId: id, name });
+            summary = `Duplicated flow ${id}`;
+            break;
+          }
+          // Deploy
+          case "deploy": {
+            if (!id) throw new Error("id (flowId) required for deploy");
+            const progressToken = extra._meta?.progressToken;
+            data = await deploy({
+              flowId: id,
+              wait: wait ?? true,
+              flowName,
+              onStatus: (s, sub) => {
+                if (!progressToken) return;
+                const stages = {
+                  bundling: 15,
+                  deploying: 55,
+                  published: 100,
+                  active: 100,
+                  failed: 100
+                };
+                extra.sendNotification({
+                  method: "notifications/progress",
+                  params: {
+                    progressToken,
+                    progress: stages[s] ?? 0,
+                    total: 100,
+                    message: sub ? `${s}:${sub}` : s
+                  }
+                });
+              },
+              signal: extra.signal
+            });
+            const st = data.status;
+            const deployData = data;
+            if (st === "failed") {
+              const msg = `Deploy failed: ${deployData.errorMessage ?? "unknown error"}`;
+              return mcpResult8({ action, ok: false, data }, msg, {
+                next: ["Run flow_validate to check your configuration"]
+              });
+            } else {
+              summary = `Deployed flow ${id} \u2014 status: ${st}`;
+              const publicUrl = deployData.publicUrl;
+              const containerUrl = deployData.containerUrl;
+              const deployType = deployData.type;
+              const nextHints = [];
+              if (deployType === "web" && publicUrl) {
+                nextHints.push(`Bundle at ${publicUrl}`);
+                nextHints.push(`Add <script src='${publicUrl}'></script>`);
+              } else if (deployType === "server" && containerUrl) {
+                nextHints.push(`Container at ${containerUrl}`);
+                nextHints.push(`Test: curl ${containerUrl}/health`);
+              }
+              if (nextHints.length > 0) {
+                return mcpResult8({ action, ok: true, data }, summary, {
+                  next: nextHints
+                });
+              }
             }
-          ],
-          isError: true
-        };
+            break;
+          }
+          // Deployments
+          case "deployment.get": {
+            if (!id)
+              throw new Error(
+                "id (flowId or slug) required for deployment.get"
+              );
+            try {
+              data = await getDeployment({ flowId: id, flowName });
+            } catch {
+              data = await getDeploymentBySlug({ slug: id });
+            }
+            summary = `Deployment ${data.slug ?? id} \u2014 ${data.status}`;
+            break;
+          }
+          case "deployment.list": {
+            data = await listDeployments({
+              projectId: id,
+              type,
+              status
+            });
+            summary = `${(data.deployments ?? []).length} deployments`;
+            break;
+          }
+          case "deployment.create": {
+            if (!type)
+              throw new Error(
+                "type (web/server) required for deployment.create"
+              );
+            data = await createDep({ type, label: name, projectId: id });
+            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}`;
+            break;
+          }
+          default:
+            throw new Error(
+              `Unknown action: ${action}. Use one of: ${ACTIONS.join(", ")}`
+            );
+        }
+        return mcpResult8({ action, ok: true, data }, summary);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : "";
+        if (msg.includes("401") || msg.includes("403") || msg.includes("Unauthorized"))
+          return mcpError8(
+            error,
+            "Set WALKEROS_TOKEN env var or check token expiry"
+          );
+        if (msg.includes("required"))
+          return mcpError8(
+            error,
+            `See api tool description for ${action} parameters.`
+          );
+        return mcpError8(error);
       }
     }
   );
@@ -839,25 +1210,14 @@ function registerGetPackageSchemaTool(server2) {
 
 // src/resources/package-schemas.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { fetchPackageSchema as fetchPackageSchema2 } from "@walkeros/core";
-var KNOWN_PACKAGES = [
-  "@walkeros/web-destination-google-ga4",
-  "@walkeros/web-destination-meta-pixel",
-  "@walkeros/web-destination-plausible",
-  "@walkeros/web-destination-snowplow",
-  "@walkeros/web-destination-piwikpro",
-  "@walkeros/web-destination-etag",
-  "@walkeros/web-destination-bigquery",
-  "@walkeros/web-source-walker",
-  "@walkeros/web-source-datalayer"
-];
+import { fetchPackageSchema } from "@walkeros/core";
 function registerPackageSchemaResources(server2) {
   const template = new ResourceTemplate("walkeros://schema/{packageName}", {
     list: async () => ({
-      resources: KNOWN_PACKAGES.map((pkg) => ({
-        uri: `walkeros://schema/${encodeURIComponent(pkg)}`,
-        name: pkg,
-        description: `Schema and examples for ${pkg}`,
+      resources: PACKAGE_REGISTRY.map((pkg) => ({
+        uri: `walkeros://schema/${encodeURIComponent(pkg.name)}`,
+        name: pkg.name,
+        description: `Schema and examples for ${pkg.name}`,
         mimeType: "application/json"
       }))
     })
@@ -871,7 +1231,7 @@ function registerPackageSchemaResources(server2) {
       mimeType: "application/json"
     },
     async (uri, { packageName }) => {
-      const info = await fetchPackageSchema2(
+      const info = await fetchPackageSchema(
         decodeURIComponent(packageName)
       );
       return {
@@ -887,72 +1247,508 @@ function registerPackageSchemaResources(server2) {
   );
 }
 
-// src/resources/flows.ts
-import { listFlows as listFlows2, getFlow as getFlow2 } from "@walkeros/cli";
-import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp.js";
-function registerFlowResources(server2) {
-  const template = new ResourceTemplate2("walkeros://flow/{flowId}", {
-    list: async () => {
+// src/resources/references.ts
+import { schemas as schemas5 } from "@walkeros/core/dev";
+function registerReferenceResources(server2) {
+  server2.resource(
+    "flow-schema",
+    "walkeros://reference/flow-schema",
+    {
+      description: "JSON Schema for Flow.Config \u2014 the complete flow configuration structure",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/flow-schema",
+          text: JSON.stringify(schemas5.configJsonSchema, null, 2),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "event-model",
+    "walkeros://reference/event-model",
+    {
+      description: "JSON Schema for walkerOS events: entity-action naming, data, context, globals, user, consent",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/event-model",
+          text: JSON.stringify(schemas5.eventJsonSchema, null, 2),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "mapping",
+    "walkeros://reference/mapping",
+    {
+      description: "JSON Schemas for walkerOS mapping: rules, valueConfig, rule, policy",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/mapping",
+          text: JSON.stringify(
+            {
+              rules: schemas5.rulesJsonSchema,
+              valueConfig: schemas5.valueConfigJsonSchema,
+              rule: schemas5.ruleJsonSchema,
+              policy: schemas5.policyJsonSchema
+            },
+            null,
+            2
+          ),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "consent",
+    "walkeros://reference/consent",
+    {
+      description: "JSON Schema for walkerOS consent: destination-level, rule-level, and field-level consent gating",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/consent",
+          text: JSON.stringify(schemas5.consentJsonSchema, null, 2),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "variables",
+    "walkeros://reference/variables",
+    {
+      description: "walkerOS variable patterns: $var, $env, $def, $contract, $code, $store substitution",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/variables",
+          text: JSON.stringify(
+            {
+              patterns: {
+                "$var.name": "Variable substitution \u2014 cascade: step settings > flow settings > config variables",
+                "$env.NAME": "Environment variable \u2014 $env.GA_ID reads process.env.GA_ID",
+                "$env.NAME:default": "Environment variable with fallback \u2014 $env.GA_ID:G-DEFAULT",
+                "$def.name": "Definition reference \u2014 reusable config blocks from definitions section",
+                "$def.name.path.deep": "Nested definition access \u2014 $def.ga4Events.purchase",
+                "$contract.name": "Contract reference \u2014 links to named contract for validation",
+                "$contract.name.path": "Nested contract access \u2014 $contract.ecommerce.product",
+                "$code:(expr)": "Inline JavaScript \u2014 $code:(event) => event.data.price * 100",
+                "$store:storeId": "Store injection in env values \u2014 wires runtime store access"
+              },
+              cascade: {
+                priority: [
+                  "1. Step-level settings (highest)",
+                  "2. Flow-level settings",
+                  "3. Config-level variables (lowest)"
+                ],
+                example: {
+                  variables: { apiKey: "default-key" },
+                  flows: {
+                    production: {
+                      destinations: {
+                        api: {
+                          config: { key: "$var.apiKey" },
+                          settings: { apiKey: "prod-key" }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            null,
+            2
+          ),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "contract",
+    "walkeros://reference/contract",
+    {
+      description: "JSON Schema for walkerOS contracts: event schema validation with entity-action keying",
+      mimeType: "application/json"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "walkeros://reference/contract",
+          text: JSON.stringify(schemas5.contractJsonSchema, null, 2),
+          mimeType: "application/json"
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "examples",
+    "walkeros://reference/examples",
+    {
+      description: "Complete flow config example: web + server flows, mapping, contracts, step examples",
+      mimeType: "application/json"
+    },
+    async () => {
+      let example;
       try {
-        const { flows } = await listFlows2({});
-        return {
-          resources: flows.map((f) => ({
-            uri: `walkeros://flow/${f.id}`,
-            name: f.name,
-            mimeType: "application/json"
-          }))
-        };
+        const { readFileSync } = await import("fs");
+        const { createRequire } = await import("module");
+        const require2 = createRequire(import.meta.url);
+        const examplePath = require2.resolve("@walkeros/cli/examples/flow-complete.json");
+        example = readFileSync(examplePath, "utf-8");
       } catch {
-        return { resources: [] };
+        example = JSON.stringify({ error: "Example not found" });
       }
+      return {
+        contents: [
+          {
+            uri: "walkeros://reference/examples",
+            text: example,
+            mimeType: "application/json"
+          }
+        ]
+      };
     }
-  });
-  server2.registerResource(
-    "flow-config",
-    template,
+  );
+  server2.resource(
+    "api",
+    "walkeros://reference/api",
     {
-      title: "walkerOS Flow Configuration",
-      description: "Flow configurations from your walkerOS project",
+      description: "walkerOS cloud API \u2014 OpenAPI 3.1 specification",
       mimeType: "application/json"
     },
-    async (uri, { flowId: flowId2 }) => {
-      const flow = await getFlow2({ flowId: flowId2 });
+    async () => {
+      let openApiSpec;
+      try {
+        const { readFileSync } = await import("fs");
+        const { createRequire } = await import("module");
+        const require2 = createRequire(import.meta.url);
+        const specPath = require2.resolve("@walkeros/cli/openapi/spec.json");
+        openApiSpec = readFileSync(specPath, "utf-8");
+      } catch {
+        openApiSpec = JSON.stringify({ error: "OpenAPI spec not found" });
+      }
       return {
         contents: [
           {
-            uri: uri.toString(),
-            mimeType: "application/json",
-            text: JSON.stringify(flow, null, 2)
+            uri: "walkeros://reference/api",
+            text: openApiSpec,
+            mimeType: "application/json"
           }
         ]
       };
     }
   );
+  server2.resource(
+    "packages",
+    "walkeros://reference/packages",
+    {
+      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"
+        }
+      ]
+    })
+  );
+}
+
+// src/prompts/add-step.ts
+import { z as z8 } 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: z8.string().optional().describe(
+          "Type of step to add: source, destination, transformer, or store"
+        ),
+        flowPath: z8.string().optional().describe("Path to the flow.json file to modify")
+      }
+    },
+    async ({ stepType, flowPath }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              `Help me add a ${stepType || "new"} step to my flow${flowPath ? ` at ${flowPath}` : ""}.`,
+              "",
+              "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.`,
+              '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.",
+              '6. For destinations: configure mapping using nested entity \u2192 action keys. Event "product add" maps to `{ "product": { "add": { name: "AddToCart" } } }`. Use the setup-mapping prompt for guidance.',
+              "7. Use flow_validate to verify the result.",
+              "",
+              "Important:",
+              "- Read the walkeros://reference/flow-schema resource to understand connection rules.",
+              "- Sources connect to pre-collector transformers via `next`.",
+              "- Destinations connect to post-collector transformers via `before`.",
+              "- Stores are passive \u2014 referenced via `$store:storeName` in env values.",
+              "- Use variables ($var) for values that change between environments.",
+              "- For required settings without defaults in the package schema, ask the user which value to use. Do not guess credentials, IDs, or environment-specific values."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+}
+
+// src/prompts/setup-mapping.ts
+import { z as z9 } 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: z9.string().optional().describe('Step name in the flow (e.g., "gtag", "meta", "express")')
+      }
+    },
+    async ({ stepName }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              `Help me set up mapping${stepName ? ` for the "${stepName}" step` : ""}.`,
+              "",
+              "IMPORTANT \u2014 Mapping key structure:",
+              "Mapping uses NESTED entity \u2192 action keys, NOT dot-separated strings.",
+              'Event name "product add" splits into entity "product" and action "add".',
+              'Config structure: `{ "mapping": { "product": { "add": { name: "AddToCart", data: { ... } } } } }`',
+              'Wildcards: `{ "*": { "view": Rule } }` matches any entity with action "view".',
+              "",
+              "Follow these steps:",
+              "1. Read the walkeros://reference/mapping resource for full syntax reference.",
+              `2. ${stepName ? `Identify the package for "${stepName}" in the flow, then u` : "U"}se package_get with section="examples" to see how events are mapped for this package.`,
+              '3. Ask which events I want to map (e.g., "product view", "order complete").',
+              "4. Generate mapping rules using the package examples as templates.",
+              "5. Use flow_validate to verify the mapping.",
+              "",
+              "Mapping operates at two levels:",
+              "- **Source mapping**: normalizes raw input \u2192 walkerOS events",
+              "- **Destination mapping**: transforms walkerOS events \u2192 vendor format",
+              "",
+              "Key mapping operators: data (extract), map (object transform), loop (array processing), ",
+              "set (create array), fn ($code function), condition (conditional), consent (consent-gated).",
+              "",
+              "Use $def references for shared mapping patterns across destinations."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+}
+
+// src/prompts/manage-contract.ts
+import { z as z10 } 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: z10.string().optional().describe(
+          'Direction: "from-mappings" (extract contract from existing mappings), "from-scratch" (create new contract), or "to-mappings" (scaffold mappings from contract)'
+        )
+      }
+    },
+    async ({ direction }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              `Help me ${direction === "to-mappings" ? "scaffold mappings from a contract" : direction === "from-mappings" ? "generate a contract from existing mappings" : "manage event contracts"}.`,
+              "",
+              "Follow these steps:",
+              "1. Read the walkeros://reference/contract resource to understand contract structure.",
+              direction === "from-mappings" ? "2. Read all destination mappings in the flow, extract referenced event fields, and generate a contract with those as required properties." : direction === "to-mappings" ? "2. Read the contract from the flow, then scaffold mapping stubs for each destination based on the contract fields." : "2. Ask for entity-action names and required properties, or ask whether to generate from existing mappings.",
+              "3. Use entity-action keying with wildcards (*.*, *.action, entity.*) for broad rules.",
+              "4. Define JSON Schema for events, globals, context, custom, user, and consent.",
+              "5. Use flow_validate to verify the contract.",
+              "",
+              "Contracts and mappings are bidirectional:",
+              "- **Contract \u2192 Mappings**: contract defines what events look like, mappings are scaffolded to match.",
+              "- **Mappings \u2192 Contract**: existing mappings reveal which fields are used, contract formalizes them.",
+              "",
+              "Use $contract.name references to link contracts in the flow.",
+              "Contracts support extends for inheritance between event types."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+}
+
+// src/prompts/use-definitions.ts
+import { z as z11 } 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: z11.string().optional().describe("Path to the flow.json file to analyze")
+      }
+    },
+    async ({ flowPath }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              `Help me extract shared patterns into definitions and variables${flowPath ? ` in ${flowPath}` : ""}.`,
+              "",
+              "Follow these steps:",
+              "1. Read the walkeros://reference/variables resource to understand variable syntax.",
+              "2. Analyze the flow config for repeated patterns (same mapping blocks, same config values).",
+              "3. Extract repeated mapping patterns into the `definitions` section with `$def.name` references.",
+              "4. Extract environment-specific values into `variables` with `$var.name` references.",
+              "5. Show the cascade priority: step > settings > config.",
+              "6. Use flow_validate to verify the result.",
+              "",
+              "Variable types:",
+              "- `$var.name` \u2014 variable substitution (cascade: step > settings > config)",
+              "- `$env.NAME` and `$env.NAME:default` \u2014 environment variables",
+              "- `$def.name` and `$def.name.path.deep` \u2014 definition references",
+              "- `$contract.name` \u2014 contract references",
+              "- `$code:(expr)` \u2014 inline JavaScript functions",
+              "- `$store:storeId` \u2014 store injection in env values",
+              "",
+              "Look for:",
+              "- Same API keys or URLs across multiple destinations \u2192 $var or $env",
+              "- Identical mapping rules in multiple destinations \u2192 $def",
+              "- Environment-specific values (dev/staging/prod) \u2192 $var with overrides"
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
 }
 
 // src/index.ts
-var server = new McpServer({
-  name: "walkeros",
-  version: "2.0.1"
-});
-registerBundleTool(server);
-registerSimulateTool(server);
-registerPushTool(server);
-registerValidateTool(server);
-registerAuthTools(server);
-registerProjectTools(server);
-registerFlowTools(server);
-registerDeployTools(server);
+var server = new McpServer(
+  {
+    name: "walkeros-flow",
+    version: "3.0.0"
+  },
+  {
+    instructions: `walkerOS is an open-source, privacy-first event data collection platform. Define event pipelines as code using JSON flow configurations.
+
+## Architecture: Source \u2192 Collector \u2192 Destination(s)
+
+Every component in a flow is a **step**: sources capture events, transformers process them, destinations deliver them, stores provide shared state. Steps connect via \`next\` (pre-collector) and \`before\` (post-collector) chains.
+
+## Flow Config Structure
+
+Every flow config follows this shape:
+
+\`\`\`json
+{
+  "version": 3,
+  "flows": {
+    "default": {
+      "web": {},
+      "sources": { "<name>": { "package": "<npm-package>", "config": {} } },
+      "destinations": { "<name>": { "package": "<npm-package>", "config": { "settings": {} } } }
+    }
+  }
+}
+\`\`\`
+
+Event format: \`{ name: "entity action", data: {...}, entity: "...", action: "..." }\`. Sources convert raw input into this format.
+
+Key rules:
+- \`version: 3\` is required
+- Each flow must have exactly one of \`web: {}\` or \`server: {}\`
+- Destination settings go inside \`config.settings\`, not directly on the destination
+- Read \`walkeros://reference/flow-schema\` for the full annotated structure
+
+## Getting Started
+
+1. \`flow_load({ platform: "web" })\` or \`flow_load({ source: "./flow.json" })\` \u2014 create or load a flow
+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
+5. \`flow_validate({ type: "flow", input: "flow.json" })\` \u2014 verify configuration
+6. \`flow_simulate({ configPath: "flow.json", event: "..." })\` \u2014 test with mocked API calls
+7. \`flow_bundle({ configPath: "flow.json" })\` \u2014 build deployable JavaScript
+8. \`api({ action: "deploy", id: "cfg_..." })\` \u2014 deploy to walkerOS cloud (requires WALKEROS_TOKEN env var; unavailable without it)
+
+If validation fails, fix the reported errors and re-validate. Do not skip validation.
+
+## Reference Resources
+
+Read these before constructing configs manually: \`walkeros://reference/flow-schema\`, \`walkeros://reference/mapping\`, \`walkeros://reference/event-model\`, \`walkeros://reference/consent\`, \`walkeros://reference/variables\`, \`walkeros://reference/contract\`, \`walkeros://reference/examples\`.
+
+## 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.
+- **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.
+- **Consent** gates destinations, mapping rules, and individual fields. Privacy-first by design.`
+  }
+);
+registerFlowValidateTool(server);
+registerFlowBundleTool(server);
+registerFlowSimulateTool(server);
+registerFlowPushTool(server);
+registerFlowExamplesTool(server);
+registerPackageSearchTool(server);
 registerGetPackageSchemaTool(server);
+registerFlowLoadTool(server);
 registerPackageSchemaResources(server);
-registerFlowResources(server);
+registerReferenceResources(server);
+registerAddStepPrompt(server);
+registerSetupMappingPrompt(server);
+registerManageContractPrompt(server);
+registerUseDefinitionsPrompt(server);
+if (process.env.WALKEROS_TOKEN) {
+  registerApiTool(server);
+}
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("walkerOS MCP server running on stdio");
+  console.error("walkerOS Flow MCP server running on stdio");
 }
 main().catch((error) => {
-  console.error("Failed to start MCP server:", error);
+  console.error("Failed to start Flow MCP server:", error);
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map