@kadoa/mcp 0.5.5 → 0.5.7

package/README.md

@@ -85,6 +85,17 @@ Claude checks the run status with get_workflow, then calls fetch_data
 to retrieve the extracted records and display them as a table.
 ```
 
+### Create a workflow from a template
+
+```
+> You: Use my "Product Scraper" template to scrape https://example-shop.com.
+
+Claude calls list_templates to find the matching template, then
+create_workflow with `templateId` and `urls` only — the prompt and
+schema are inherited from the template version. Returns the workflow
+ID for follow-up with get_workflow or fetch_data.
+```
+
 ### Update a workflow and re-run
 
 ```

package/dist/index.js

@@ -14552,7 +14552,7 @@ function finalize(ctx, schema) {
     result.$schema = "http://json-schema.org/draft-07/schema#";
   } else if (ctx.target === "draft-04") {
     result.$schema = "http://json-schema.org/draft-04/schema#";
-  } else if (ctx.target === "openapi-3.0") {} else {}
+  } else if (ctx.target === "openapi-3.0") {}
   if (ctx.external?.uri) {
     const id = ctx.external.registry.get(schema)?.id;
     if (!id)
@@ -14817,7 +14817,7 @@ var formatMap, stringProcessor = (schema, ctx, _json, _params) => {
     if (val === undefined) {
       if (ctx.unrepresentable === "throw") {
         throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-      } else {}
+      }
     } else if (typeof val === "bigint") {
       if (ctx.unrepresentable === "throw") {
         throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -44498,9 +44498,9 @@ function createClientDomains(params) {
   const dataFetcherService = new DataFetcherService(client.apis.workflows);
   const channelsService = new NotificationChannelsService(client.apis.notifications, userService);
   const settingsService = new NotificationSettingsService(client.apis.notifications);
-  const workflowsCoreService = new WorkflowsCoreService(client.apis.workflows);
   const schemasService = new SchemasService(client);
   const templatesService = new TemplatesService(client);
+  const workflowsCoreService = new WorkflowsCoreService(client.apis.workflows, templatesService);
   const variablesService = new VariablesService(client);
   const channelSetupService = new NotificationSetupService(channelsService, settingsService);
   const coreService = new ValidationCoreService(client);
@@ -48714,7 +48714,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }));
     return channels;
   }
-}, PUBLIC_API_URI, WSS_API_URI, REALTIME_API_URI, SDK_VERSION = "0.32.0", SDK_NAME = "kadoa-node-sdk", SDK_LANGUAGE = "node", debug6, isDrainControlMessage = (message) => message.type === "control.draining", isRealtimeEvent = (message) => message.type !== "heartbeat" && message.type !== "control.draining", _Realtime = class _Realtime2 {
+}, PUBLIC_API_URI, WSS_API_URI, REALTIME_API_URI, SDK_VERSION = "0.33.0", SDK_NAME = "kadoa-node-sdk", SDK_LANGUAGE = "node", debug6, isDrainControlMessage = (message) => message.type === "control.draining", isRealtimeEvent = (message) => message.type !== "heartbeat" && message.type !== "control.draining", _Realtime = class _Realtime2 {
   constructor(config2) {
     this.drainingSockets = /* @__PURE__ */ new Set;
     this.lastHeartbeat = Date.now();
@@ -49443,36 +49443,82 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     });
   }
 }, JobStateEnum, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES2, debug9, WorkflowsCoreService = class {
-  constructor(workflowsApi) {
+  constructor(workflowsApi, templatesService) {
     this.workflowsApi = workflowsApi;
+    this.templatesService = templatesService;
   }
   async create(input) {
     validateAdditionalData(input.additionalData);
-    if (!input.userPrompt) {
+    const isFromTemplate = input.templateId != null;
+    if (isFromTemplate) {
+      const conflicting = [];
+      if (input.userPrompt != null)
+        conflicting.push("userPrompt");
+      if (input.entity != null)
+        conflicting.push("entity");
+      if (input.fields != null)
+        conflicting.push("fields");
+      if (input.schemaId != null)
+        conflicting.push("schemaId");
+      if (input.monitoring != null)
+        conflicting.push("monitoring");
+      if (input.navigationMode != null)
+        conflicting.push("navigationMode");
+      if (conflicting.length > 0) {
+        throw new KadoaSdkException(`Fields are defined by the template and cannot be supplied when creating from a template: ${conflicting.join(", ")}`, {
+          code: "VALIDATION_ERROR",
+          details: { conflicting }
+        });
+      }
+    } else if (!input.userPrompt) {
       throw new KadoaSdkException("userPrompt is required to create a workflow", {
         code: "VALIDATION_ERROR",
         details: { urls: input.urls }
       });
     }
     const domainName = new URL(input.urls[0]).hostname;
-    const request = {
-      urls: input.urls,
-      name: input.name ?? domainName,
-      description: input.description,
-      userPrompt: input.userPrompt,
-      navigationMode: "agentic-navigation",
-      schemaId: input.schemaId,
-      ...input.entity != null && { entity: input.entity },
-      fields: input.fields,
-      bypassPreview: input.bypassPreview ?? true,
-      tags: input.tags,
-      interval: input.interval,
-      monitoring: input.monitoring,
-      location: input.location,
-      schedules: input.schedules,
-      additionalData: input.additionalData,
-      limit: input.limit
-    };
+    let request;
+    if (isFromTemplate) {
+      const templateId = input.templateId;
+      const templateVersion = input.templateVersion ?? await this.resolveLatestVersion(templateId);
+      request = {
+        urls: input.urls,
+        templateId,
+        templateVersion,
+        ...input.name != null && { name: input.name },
+        ...input.description != null && { description: input.description },
+        ...input.tags != null && { tags: input.tags },
+        ...input.interval != null && { interval: input.interval },
+        ...input.schedules != null && { schedules: input.schedules },
+        ...input.location != null && { location: input.location },
+        ...input.bypassPreview != null && {
+          bypassPreview: input.bypassPreview
+        },
+        ...input.additionalData != null && {
+          additionalData: input.additionalData
+        },
+        ...input.limit != null && { limit: input.limit }
+      };
+    } else {
+      request = {
+        urls: input.urls,
+        name: input.name ?? domainName,
+        description: input.description,
+        userPrompt: input.userPrompt,
+        navigationMode: "agentic-navigation",
+        schemaId: input.schemaId,
+        ...input.entity != null && { entity: input.entity },
+        fields: input.fields,
+        bypassPreview: input.bypassPreview ?? true,
+        tags: input.tags,
+        interval: input.interval,
+        monitoring: input.monitoring,
+        location: input.location,
+        schedules: input.schedules,
+        additionalData: input.additionalData,
+        limit: input.limit
+      };
+    }
     const response = await this.workflowsApi.v4WorkflowsPost({
       publicWorkflowCreateRequest: request
     });
@@ -49487,6 +49533,23 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }
     return { id: workflowId };
   }
+  async resolveLatestVersion(templateId) {
+    if (!this.templatesService) {
+      throw new KadoaSdkException("TemplatesService is required to resolve a template's latest version. Pass `templateVersion` explicitly or construct WorkflowsCoreService with a TemplatesService.", {
+        code: "INTERNAL_ERROR",
+        details: { templateId }
+      });
+    }
+    const template = await this.templatesService.get(templateId);
+    const latest = template.latestVersion;
+    if (latest == null) {
+      throw new KadoaSdkException(`Template ${templateId} has no published versions; supply templateVersion explicitly or publish a version first.`, {
+        code: "VALIDATION_ERROR",
+        details: { templateId }
+      });
+    }
+    return latest;
+  }
   async get(id) {
     const response = await this.workflowsApi.v4WorkflowsWorkflowIdGet({
       workflowId: id
@@ -50848,7 +50911,7 @@ function registerTools(server, ctx) {
     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")'),
+    prompt: exports_external.string().optional().describe('Natural language description of what to extract (e.g., "Extract product prices and names"). Required unless templateId is provided.'),
     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.")
@@ -50953,10 +51016,12 @@ function registerTools(server, ctx) {
 
 ` + "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.
 
-` + "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.",
+` + "PREFER TEMPLATES: If the user's request matches an existing template, instantiate it via `templateId` instead of writing a fresh prompt/schema. " + "Use `list_templates` to discover available templates and `get_template` to inspect schemas before deciding. " + "When `templateId` is set, only `urls` is required — `prompt`, `entity`, and `schema` must NOT be supplied; they are inherited from the template version.\n\n" + "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({
       ...extractionInputShape,
       ...urlInputShape,
+      templateId: exports_external.string().optional().describe("Instantiate this workflow from a published template. When set, only 'urls' is required — prompt/entity/schema must NOT be supplied; they are inherited from the template version. Discover templates via list_templates."),
+      templateVersion: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Specific published template version (integer) to instantiate. Defaults to the latest published version when templateId is set."),
       description: exports_external.string().max(500).optional().describe("Description of what this workflow does (max 500 characters)"),
       tags: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string())).optional().describe("Tags for organizing workflows"),
       limit: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Maximum number of records to extract per run. Useful for limiting scope or cost control."),
@@ -50991,32 +51056,62 @@ function registerTools(server, ctx) {
     if (args.updateInterval === "CUSTOM" && (!args.schedules || args.schedules.length === 0)) {
       return errorResult("updateInterval='CUSTOM' requires at least one cron expression in the 'schedules' field (e.g. '0 8 * * 2' for Tuesdays at 8am UTC).");
     }
-    let builder = ctx.client.extract({
-      urls,
-      name: args.name || "Untitled Workflow",
-      userPrompt: args.prompt,
-      extraction: buildExtraction(args),
-      interval: args.updateInterval,
-      description: args.description,
-      schedules: args.schedules
-    });
     const n = args.notifications;
-    const hasNotifications = n && (n.email || n.webhook || n.slack || n.websocket);
-    if (hasNotifications) {
-      builder = builder.withNotifications({
-        events: ["workflow_data_change"],
-        channels: buildNotificationChannels(n)
+    const hasNotifications = !!(n && (n.email || n.webhook || n.slack || n.websocket));
+    let workflowId;
+    if (args.templateId) {
+      if (args.prompt || args.entity || args.schema) {
+        return errorResult("When 'templateId' is set, 'prompt', 'entity', and 'schema' must NOT be supplied — they are inherited from the template version.");
+      }
+      const { id } = await ctx.client.workflow.create({
+        urls,
+        name: args.name || "Untitled Workflow",
+        description: args.description,
+        interval: args.updateInterval,
+        schedules: args.schedules,
+        tags: args.tags && args.tags.length > 0 ? args.tags : undefined,
+        limit: args.limit,
+        templateId: args.templateId,
+        templateVersion: args.templateVersion
       });
-    }
-    const workflow = await builder.create();
-    const needsUpdate = args.limit !== undefined || args.tags && args.tags.length > 0;
-    if (needsUpdate) {
-      const updates = {};
-      if (args.limit !== undefined)
-        updates.limit = args.limit;
-      if (args.tags && args.tags.length > 0)
-        updates.tags = args.tags;
-      await ctx.client.workflow.update(workflow.workflowId, updates);
+      workflowId = id;
+      if (hasNotifications) {
+        await ctx.client.notification.configure({
+          workflowId,
+          events: ["workflow_data_change"],
+          channels: buildNotificationChannels(n)
+        });
+      }
+    } else {
+      if (!args.prompt) {
+        return errorResult("'prompt' is required unless 'templateId' is provided.");
+      }
+      let builder = ctx.client.extract({
+        urls,
+        name: args.name || "Untitled Workflow",
+        userPrompt: args.prompt,
+        extraction: buildExtraction(args),
+        interval: args.updateInterval,
+        description: args.description,
+        schedules: args.schedules
+      });
+      if (hasNotifications) {
+        builder = builder.withNotifications({
+          events: ["workflow_data_change"],
+          channels: buildNotificationChannels(n)
+        });
+      }
+      const workflow = await builder.create();
+      workflowId = workflow.workflowId;
+      const needsUpdate = args.limit !== undefined || args.tags && args.tags.length > 0;
+      if (needsUpdate) {
+        const updates = {};
+        if (args.limit !== undefined)
+          updates.limit = args.limit;
+        if (args.tags && args.tags.length > 0)
+          updates.tags = args.tags;
+        await ctx.client.workflow.update(workflowId, updates);
+      }
     }
     const enabledChannels = await describeNotifications(n);
     let message = "Workflow created successfully. The AI agent will start extracting data automatically.";
@@ -51026,8 +51121,8 @@ function registerTools(server, ctx) {
     message += " Use fetch_data to retrieve the latest extracted results.";
     return jsonResult({
       success: true,
-      workflowId: workflow.workflowId,
-      dashboardUrl: workflowDashboardUrl(workflow.workflowId),
+      workflowId,
+      dashboardUrl: workflowDashboardUrl(workflowId),
       message
     });
   }));
@@ -51987,7 +52082,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kadoa/mcp",
-    version: "0.5.5",
+    version: "0.5.7",
     description: "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
     type: "module",
     main: "dist/index.js",
@@ -52011,7 +52106,7 @@ var init_package = __esm(() => {
       prepublishOnly: "bun run check-types && bun run test:unit && bun run build"
     },
     dependencies: {
-      "@kadoa/node-sdk": "^0.32.0",
+      "@kadoa/node-sdk": "^0.33.0",
       "@modelcontextprotocol/sdk": "^1.26.0",
       express: "^5.2.1",
       ioredis: "^5.6.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
     "prepublishOnly": "bun run check-types && bun run test:unit && bun run build"
   },
   "dependencies": {
-    "@kadoa/node-sdk": "^0.32.0",
+    "@kadoa/node-sdk": "^0.33.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "express": "^5.2.1",
     "ioredis": "^5.6.1",