@kadoa/mcp 0.3.5-rc.5 → 0.3.5-rc.7

package/dist/index.js

@@ -49312,21 +49312,88 @@ function registerTools(server, ctx) {
       }))
     });
   }));
+  const urlInputShape = {
+    url: exports_external.string().optional().describe("Single URL — prefer using 'urls' instead. If both are provided, 'urls' takes precedence."),
+    urls: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).optional().describe("Starting URLs for the workflow (array of strings). Also accepts a single URL string.")
+  };
+  const extractionInputShape = {
+    prompt: exports_external.string().describe('Natural language description of what to extract (e.g., "Extract product prices and names")'),
+    name: exports_external.string().optional().describe("Optional name for the workflow"),
+    entity: exports_external.string().optional().describe("Entity name for extraction (e.g., 'Product', 'Job Posting')"),
+    schema: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(SchemaFieldShape))).optional().describe("Extraction schema fields. If omitted, the AI agent auto-detects the schema.")
+  };
+  const notificationsInputShape = {
+    notifications: exports_external.object({
+      email: exports_external.boolean().optional().describe("Send email notifications to the account email when data changes"),
+      webhook: exports_external.object({
+        url: exports_external.string().url().describe("Webhook endpoint URL"),
+        httpMethod: exports_external.enum(["POST", "GET", "PUT", "PATCH"]).optional().describe("HTTP method (defaults to POST)")
+      }).optional().describe("Send notifications via HTTP webhook"),
+      slack: exports_external.object({
+        webhookUrl: exports_external.string().url().describe("Slack incoming webhook URL")
+      }).optional().describe("Send notifications to a Slack channel"),
+      websocket: exports_external.boolean().optional().describe("Enable WebSocket notifications for programmatic real-time consumption")
+    }).optional().describe("Notification channels to alert when data changes.")
+  };
+  function resolveUrls(args) {
+    const urls = args.urls ?? (args.url ? [args.url] : []);
+    return urls.length > 0 ? urls : null;
+  }
+  function buildExtraction(args) {
+    if (!args.schema)
+      return;
+    return (builder) => {
+      const entity = builder.entity(args.entity || "Data");
+      for (const field of args.schema) {
+        entity.field(field.name, field.description || field.name, field.dataType || "STRING", { example: field.example });
+      }
+      return entity;
+    };
+  }
+  function buildNotificationChannels(n) {
+    const channels = {};
+    if (n.email)
+      channels.EMAIL = true;
+    if (n.websocket)
+      channels.WEBSOCKET = true;
+    if (n.webhook) {
+      channels.WEBHOOK = {
+        name: "mcp-webhook",
+        webhookUrl: n.webhook.url,
+        httpMethod: n.webhook.httpMethod || "POST"
+      };
+    }
+    if (n.slack) {
+      channels.SLACK = {
+        name: "mcp-slack",
+        webhookUrl: n.slack.webhookUrl
+      };
+    }
+    return channels;
+  }
+  async function describeNotifications(n) {
+    if (!n)
+      return [];
+    const channels = [];
+    if (n.email) {
+      const user = await ctx.client.user.getCurrentUser();
+      channels.push(`email (${user.email})`);
+    }
+    if (n.slack)
+      channels.push(`slack (${n.slack.webhookUrl})`);
+    if (n.webhook)
+      channels.push(`webhook (${n.webhook.url})`);
+    if (n.websocket)
+      channels.push("websocket");
+    return channels;
+  }
   server.registerTool("create_workflow", {
-    description: `Create a new workflow that extracts data using agentic navigation. Supports one-time, scheduled, and real-time (continuous monitoring) modes via the interval parameter. If entity and schema are provided, they guide the extraction. Otherwise, the AI agent auto-detects the schema from the page based on the prompt. The workflow runs asynchronously and may take several minutes. Do NOT poll or sleep-wait for completion. Instead, return the workflow ID to the user and let them check back later with get_workflow or fetch_data.
+    description: "Create a data extraction workflow using agentic navigation. Supports one-time or scheduled runs. " + "If entity and schema are provided, they guide the extraction; otherwise the AI agent auto-detects the schema from the page. " + "The workflow runs asynchronously and may take several minutes. Do NOT poll or sleep-wait for completion. " + `Return the workflow ID to the user and let them check back later with get_workflow or fetch_data.
 
-` + `IMPORTANT — REAL_TIME vs regular workflows:
-` + `• REAL_TIME workflows are fundamentally different from regular extraction workflows. They route to a separate Observer service, run continuously, and cannot be triggered manually.
-` + `• A regular workflow CANNOT be converted to real-time after creation (and vice versa). The interval=REAL_TIME flag MUST be set at creation time.
-` + `• If the user wants to monitor a page for changes, set interval='REAL_TIME' here. Do NOT create a regular workflow and then try to change its interval to REAL_TIME via update_workflow — this will be rejected.
-` + "• When the user says 'monitor', 'track', 'watch', or 'alert me' — ASK if they want real-time continuous monitoring (interval='REAL_TIME') or scheduled extraction. Do NOT assume one or the other.",
+` + "NOTE: This tool is for one-time or scheduled extraction ONLY. " + "For continuous real-time monitoring (watching a page for changes and alerting), use the create_realtime_monitor tool instead.",
     inputSchema: strictSchema({
-      prompt: exports_external.string().describe('Natural language description of what to extract (e.g., "Extract product prices and names")'),
-      url: exports_external.string().optional().describe("Single URL — prefer using 'urls' instead. If both are provided, 'urls' takes precedence."),
-      urls: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).optional().describe("Starting URLs for the workflow (array of strings). Also accepts a single URL string."),
-      name: exports_external.string().optional().describe("Optional name for the workflow"),
-      entity: exports_external.string().optional().describe("Entity name for extraction (e.g., 'Product', 'Job Posting')"),
-      schema: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(SchemaFieldShape))).optional().describe("Extraction schema fields. If omitted, the AI agent auto-detects the schema."),
+      ...extractionInputShape,
+      ...urlInputShape,
       interval: exports_external.enum([
         "ONLY_ONCE",
         "EVERY_10_MINUTES",
@@ -49343,103 +49410,35 @@ function registerTools(server, ctx) {
         "BIWEEKLY",
         "TRIWEEKLY",
         "FOUR_WEEKS",
-        "MONTHLY",
-        "REAL_TIME"
-      ]).optional().describe("How often the workflow runs. Defaults to ONLY_ONCE. Use REAL_TIME for continuous monitoring."),
-      notifications: exports_external.object({
-        email: exports_external.boolean().optional().describe("Send email notifications to the account email when data changes"),
-        webhook: exports_external.object({
-          url: exports_external.string().url().describe("Webhook endpoint URL"),
-          httpMethod: exports_external.enum(["POST", "GET", "PUT", "PATCH"]).optional().describe("HTTP method (defaults to POST)")
-        }).optional().describe("Send notifications via HTTP webhook"),
-        slack: exports_external.object({
-          webhookUrl: exports_external.string().url().describe("Slack incoming webhook URL")
-        }).optional().describe("Send notifications to a Slack channel"),
-        websocket: exports_external.boolean().optional().describe("Enable WebSocket notifications for programmatic real-time consumption")
-      }).optional().describe("Notification channels to alert when data changes. At least one channel is required for REAL_TIME workflows.")
+        "MONTHLY"
+      ]).optional().describe("How often the workflow runs. Defaults to ONLY_ONCE."),
+      ...notificationsInputShape
     }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
   }, withErrorHandling("create_workflow", async (args) => {
-    const urls = args.urls ?? (args.url ? [args.url] : []);
-    if (urls.length === 0) {
+    const urls = resolveUrls(args);
+    if (!urls) {
       return errorResult("At least one URL is required. Provide 'urls' (array) or 'url' (string).");
     }
-    let interval = args.interval;
-    if (!interval && REALTIME_INTENT_KEYWORDS.test(args.prompt || "")) {
-      const answer = await elicit("Your request sounds like it could be either real-time monitoring or scheduled extraction. Which do you want?", {
-        workflowType: {
-          type: "string",
-          enum: ["Real-time monitoring (continuous, alerts on changes)", "Scheduled extraction (one-time or recurring data pull)"],
-          description: "Choose the workflow type"
-        }
-      }, ["workflowType"]);
-      if (answer === null) {} else if (typeof answer.workflowType === "string" && answer.workflowType.startsWith("Real-time")) {
-        interval = "REAL_TIME";
-      }
-    }
-    const n = args.notifications;
-    const hasNotifications = n && (n.email || n.webhook || n.slack || n.websocket);
-    if (interval === "REAL_TIME" && !hasNotifications) {
-      return errorResult("Real-time workflows require at least one notification channel so you get alerted when data changes. " + "Add a notifications object with one or more channels: email, webhook, slack, or websocket.");
-    }
-    const extraction = args.schema ? (builder2) => {
-      const entity = builder2.entity(args.entity || "Data");
-      for (const field of args.schema) {
-        entity.field(field.name, field.description || field.name, field.dataType || "STRING", { example: field.example });
-      }
-      return entity;
-    } : undefined;
-    const isRealTime = interval === "REAL_TIME";
     let builder = ctx.client.extract({
       urls,
       name: args.name || "Untitled Workflow",
-      ...isRealTime ? {} : { navigationMode: "agentic-navigation" },
+      navigationMode: "agentic-navigation",
       userPrompt: args.prompt,
-      extraction,
-      interval
+      extraction: buildExtraction(args),
+      interval: args.interval
     });
+    const n = args.notifications;
+    const hasNotifications = n && (n.email || n.webhook || n.slack || n.websocket);
     if (hasNotifications) {
-      const channels = {};
-      if (n.email)
-        channels.EMAIL = true;
-      if (n.websocket)
-        channels.WEBSOCKET = true;
-      if (n.webhook) {
-        channels.WEBHOOK = {
-          name: "mcp-webhook",
-          webhookUrl: n.webhook.url,
-          httpMethod: n.webhook.httpMethod || "POST"
-        };
-      }
-      if (n.slack) {
-        channels.SLACK = {
-          name: "mcp-slack",
-          webhookUrl: n.slack.webhookUrl
-        };
-      }
       builder = builder.withNotifications({
         events: ["workflow_data_change"],
-        channels
+        channels: buildNotificationChannels(n)
       });
     }
     const workflow = await builder.create();
-    const enabledChannels = [];
-    if (n?.email) {
-      const user = await ctx.client.user.getCurrentUser();
-      enabledChannels.push(`email (${user.email})`);
-    }
-    if (n?.slack)
-      enabledChannels.push(`slack (${n.slack.webhookUrl})`);
-    if (n?.webhook)
-      enabledChannels.push(`webhook (${n.webhook.url})`);
-    if (n?.websocket)
-      enabledChannels.push("websocket");
-    let message = "Workflow created successfully.";
-    if (interval === "REAL_TIME") {
-      message += " This real-time workflow monitors continuously — no manual runs needed.";
-    } else {
-      message += " The AI agent will start extracting data automatically.";
-    }
+    const enabledChannels = await describeNotifications(n);
+    let message = "Workflow created successfully. The AI agent will start extracting data automatically.";
     if (enabledChannels.length > 0) {
       message += ` Notifications on data changes via: ${enabledChannels.join(", ")}.`;
     }
@@ -49450,6 +49449,50 @@ function registerTools(server, ctx) {
       message
     });
   }));
+  server.registerTool("create_realtime_monitor", {
+    description: "Create a real-time monitoring workflow that continuously watches a page for changes and sends alerts. " + "Use this when the user wants to monitor, track, or watch a page in real-time. " + "At least one notification channel (email, webhook, slack, or websocket) is required so the user gets alerted on changes. " + `Real-time monitors route to a separate Observer service and CANNOT be converted to/from regular extraction workflows after creation.
+
+` + "If entity and schema are provided, they guide what to monitor; otherwise the AI agent auto-detects what to watch. " + "Do NOT poll or sleep-wait for completion. Return the workflow ID and let the user check back with get_workflow or fetch_data.",
+    inputSchema: strictSchema({
+      ...extractionInputShape,
+      ...urlInputShape,
+      ...notificationsInputShape
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+  }, withErrorHandling("create_realtime_monitor", async (args) => {
+    const urls = resolveUrls(args);
+    if (!urls) {
+      return errorResult("At least one URL is required. Provide 'urls' (array) or 'url' (string).");
+    }
+    const n = args.notifications;
+    const hasNotifications = n && (n.email || n.webhook || n.slack || n.websocket);
+    if (!hasNotifications) {
+      return errorResult("Real-time monitors require at least one notification channel so you get alerted when data changes. " + "Add a notifications object with one or more channels: email, webhook, slack, or websocket.");
+    }
+    let builder = ctx.client.extract({
+      urls,
+      name: args.name || "Untitled Monitor",
+      userPrompt: args.prompt,
+      extraction: buildExtraction(args),
+      interval: "REAL_TIME"
+    });
+    builder = builder.withNotifications({
+      events: ["workflow_data_change"],
+      channels: buildNotificationChannels(n)
+    });
+    const workflow = await builder.create();
+    const enabledChannels = await describeNotifications(n);
+    let message = "Real-time monitor created successfully. It will continuously watch for changes — no manual runs needed.";
+    if (enabledChannels.length > 0) {
+      message += ` Notifications on data changes via: ${enabledChannels.join(", ")}.`;
+    }
+    message += " Use fetch_data to retrieve the latest data.";
+    return jsonResult({
+      success: true,
+      workflowId: workflow.workflowId,
+      message
+    });
+  }));
   server.registerTool("list_workflows", {
     description: "List all workflows with their current status",
     inputSchema: {
@@ -49550,28 +49593,35 @@ function registerTools(server, ctx) {
     });
   }));
   server.registerTool("delete_workflow", {
-    description: "Delete a workflow permanently",
+    description: "Delete a workflow permanently. This is irreversible. " + "You MUST first call this tool without confirmed=true to preview what will be deleted, " + "then show the user the workflow name and ask for confirmation, " + "then call again with confirmed=true only after the user explicitly agrees.",
     inputSchema: {
-      workflowId: exports_external.string().describe("The workflow ID to delete")
+      workflowId: exports_external.string().describe("The workflow ID to delete"),
+      confirmed: exports_external.boolean().optional().describe("Set to true only after the user has explicitly confirmed deletion. Omit or set to false for the initial preview call.")
     },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
   }, withErrorHandling("delete_workflow", async (args) => {
     let workflowName = args.workflowId;
+    let workflowStatus = "unknown";
     try {
       const workflow = await ctx.client.workflow.get(args.workflowId);
       workflowName = workflow.name || args.workflowId;
+      workflowStatus = workflow.displayState ?? workflow.state ?? "unknown";
     } catch {}
-    const confirmation = await elicit(`Are you sure you want to permanently delete "${workflowName}"? This cannot be undone.`, {
-      confirm: {
-        type: "boolean",
-        description: "Confirm deletion"
+    if (!args.confirmed) {
+      const confirmation = await elicit(`Are you sure you want to permanently delete "${workflowName}" (${workflowStatus})? This cannot be undone.`, { confirm: { type: "boolean", description: "Confirm deletion" } }, ["confirm"]);
+      if (confirmation !== null) {
+        if (!confirmation.confirm) {
+          return jsonResult({ success: false, message: "Deletion cancelled by user." });
+        }
+      } else {
+        return jsonResult({
+          pending: true,
+          workflowId: args.workflowId,
+          workflowName,
+          status: workflowStatus,
+          message: `⚠️ You are about to permanently delete "${workflowName}" (${workflowStatus}). This cannot be undone. Ask the user to confirm, then call delete_workflow again with confirmed=true.`
+        });
       }
-    }, ["confirm"]);
-    if (confirmation !== null && !confirmation.confirm) {
-      return jsonResult({
-        success: false,
-        message: "Deletion cancelled by user."
-      });
     }
     await ctx.client.workflow.delete(args.workflowId);
     return jsonResult({
@@ -49700,15 +49750,26 @@ function registerTools(server, ctx) {
     });
   }));
   server.registerTool("delete_notification_channel", {
-    description: "Delete a notification channel by ID",
+    description: "Delete a notification channel by ID. " + "Call first without confirmed=true to preview, then with confirmed=true after user agrees.",
     inputSchema: {
-      channelId: exports_external.string().describe("The channel ID to delete")
+      channelId: exports_external.string().describe("The channel ID to delete"),
+      confirmed: exports_external.boolean().optional().describe("Set to true only after the user has explicitly confirmed deletion.")
     },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
   }, withErrorHandling("delete_notification_channel", async (args) => {
-    const confirmation = await elicit(`Are you sure you want to delete notification channel "${args.channelId}"?`, { confirm: { type: "boolean", description: "Confirm deletion" } }, ["confirm"]);
-    if (confirmation !== null && !confirmation.confirm) {
-      return jsonResult({ success: false, message: "Deletion cancelled by user." });
+    if (!args.confirmed) {
+      const confirmation = await elicit(`Are you sure you want to delete notification channel "${args.channelId}"?`, { confirm: { type: "boolean", description: "Confirm deletion" } }, ["confirm"]);
+      if (confirmation !== null) {
+        if (!confirmation.confirm) {
+          return jsonResult({ success: false, message: "Deletion cancelled by user." });
+        }
+      } else {
+        return jsonResult({
+          pending: true,
+          channelId: args.channelId,
+          message: `⚠️ About to delete notification channel "${args.channelId}". Ask the user to confirm, then call again with confirmed=true.`
+        });
+      }
     }
     await ctx.client.notification.channels.deleteChannel(args.channelId);
     return jsonResult({
@@ -49820,15 +49881,26 @@ function registerTools(server, ctx) {
     });
   }));
   server.registerTool("delete_notification_setting", {
-    description: "Delete a notification setting by ID. This removes the event-to-channel mapping but does not delete the channels themselves.",
+    description: "Delete a notification setting by ID. This removes the event-to-channel mapping but does not delete the channels themselves. " + "Call first without confirmed=true to preview, then with confirmed=true after user agrees.",
     inputSchema: {
-      settingsId: exports_external.string().describe("The notification settings ID to delete")
+      settingsId: exports_external.string().describe("The notification settings ID to delete"),
+      confirmed: exports_external.boolean().optional().describe("Set to true only after the user has explicitly confirmed deletion.")
     },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
   }, withErrorHandling("delete_notification_setting", async (args) => {
-    const confirmation = await elicit(`Are you sure you want to delete notification setting "${args.settingsId}"?`, { confirm: { type: "boolean", description: "Confirm deletion" } }, ["confirm"]);
-    if (confirmation !== null && !confirmation.confirm) {
-      return jsonResult({ success: false, message: "Deletion cancelled by user." });
+    if (!args.confirmed) {
+      const confirmation = await elicit(`Are you sure you want to delete notification setting "${args.settingsId}"?`, { confirm: { type: "boolean", description: "Confirm deletion" } }, ["confirm"]);
+      if (confirmation !== null) {
+        if (!confirmation.confirm) {
+          return jsonResult({ success: false, message: "Deletion cancelled by user." });
+        }
+      } else {
+        return jsonResult({
+          pending: true,
+          settingsId: args.settingsId,
+          message: `⚠️ About to delete notification setting "${args.settingsId}". Ask the user to confirm, then call again with confirmed=true.`
+        });
+      }
     }
     await ctx.client.notification.settings.deleteSettings(args.settingsId);
     return jsonResult({
@@ -49890,7 +49962,7 @@ function registerTools(server, ctx) {
     });
   }));
 }
-var SchemaFieldShape, REALTIME_INTENT_KEYWORDS;
+var SchemaFieldShape;
 var init_tools = __esm(() => {
   init_zod();
   init_dist2();
@@ -49904,7 +49976,6 @@ var init_tools = __esm(() => {
     isRequired: exports_external.boolean().optional(),
     isUnique: exports_external.boolean().optional()
   };
-  REALTIME_INTENT_KEYWORDS = /\b(monitor|track|watch|alert|real[- ]?time|live|continuous|notify)\b/i;
 });
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/middleware/hostHeaderValidation.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.3.5-rc.5",
+  "version": "0.3.5-rc.7",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",