@kadoa/mcp 0.5.14 → 0.5.16

package/README.md

@@ -66,6 +66,7 @@ Point your client to `https://mcp.kadoa.com/mcp` with OAuth authentication.
 | `list_workflows` | List all workflows with status |
 | `get_workflow` | Get detailed workflow information |
 | `get_workflow_history` | Get the workflow's configuration revision history (audit log) — who changed it, when, from which channel, and a `changedFields` summary per revision |
+| `list_workflow_runs` | List a workflow's execution run history (status, start/finish, record count, errors); filter by outcome and paginate |
 | `run_workflow` | Execute a workflow |
 | `fetch_data` | Get extracted data from a workflow |
 | `delete_workflow` | Delete a workflow |

package/dist/index.js

@@ -48467,7 +48467,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
         options: localVarRequestOptions
       };
     },
-    v4WorkflowsWorkflowIdHistoryGet: async (workflowId, options = {}) => {
+    v4WorkflowsWorkflowIdHistoryGet: async (workflowId, page, limit, status, options = {}) => {
       assertParamExists("v4WorkflowsWorkflowIdHistoryGet", "workflowId", workflowId);
       const localVarPath = `/v4/workflows/{workflowId}/history`.replace(`{${"workflowId"}}`, encodeURIComponent(String(workflowId)));
       const localVarUrlObj = new URL$1(localVarPath, DUMMY_BASE_URL);
@@ -48479,6 +48479,15 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
       const localVarHeaderParameter = {};
       const localVarQueryParameter = {};
       await setApiKeyToObject(localVarHeaderParameter, "x-api-key", configuration);
+      if (page !== undefined) {
+        localVarQueryParameter["page"] = page;
+      }
+      if (limit !== undefined) {
+        localVarQueryParameter["limit"] = limit;
+      }
+      if (status !== undefined) {
+        localVarQueryParameter["status"] = status;
+      }
       localVarHeaderParameter["Accept"] = "application/json";
       setSearchParams(localVarUrlObj, localVarQueryParameter);
       let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
@@ -48842,8 +48851,8 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
       const localVarOperationServerBasePath = operationServerMap["WorkflowsApi.v4WorkflowsWorkflowIdGet"]?.[localVarOperationServerIndex]?.url;
       return (axios2, basePath) => createRequestFunction(localVarAxiosArgs, axios_default, BASE_PATH, configuration)(axios2, localVarOperationServerBasePath || basePath);
     },
-    async v4WorkflowsWorkflowIdHistoryGet(workflowId, options) {
-      const localVarAxiosArgs = await localVarAxiosParamCreator.v4WorkflowsWorkflowIdHistoryGet(workflowId, options);
+    async v4WorkflowsWorkflowIdHistoryGet(workflowId, page, limit, status, options) {
+      const localVarAxiosArgs = await localVarAxiosParamCreator.v4WorkflowsWorkflowIdHistoryGet(workflowId, page, limit, status, options);
       const localVarOperationServerIndex = configuration?.serverIndex ?? 0;
       const localVarOperationServerBasePath = operationServerMap["WorkflowsApi.v4WorkflowsWorkflowIdHistoryGet"]?.[localVarOperationServerIndex]?.url;
       return (axios2, basePath) => createRequestFunction(localVarAxiosArgs, axios_default, BASE_PATH, configuration)(axios2, localVarOperationServerBasePath || basePath);
@@ -49308,7 +49317,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
   async executeExtraction(options) {
     this.validateOptions(options);
     const config2 = {
-      ...merge3(DEFAULT_OPTIONS, options)
+      ...merge3(merge3({}, DEFAULT_OPTIONS), options)
     };
     const isRealTime = config2.interval === "REAL_TIME";
     if (isRealTime) {
@@ -49591,7 +49600,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     assert2(startedJob.jobId, "Job ID is not set");
     debug4("Job started: %O", startedJob);
     this._jobId = startedJob.jobId;
-    const finishedJob = await this.workflowsCoreService.waitForJobCompletion(this._workflowId, startedJob.jobId);
+    const finishedJob = await this.workflowsCoreService.waitForJobCompletion(this._workflowId, startedJob.jobId, { timeoutMs: 30 * 60 * 1000 });
     debug4("Job finished: %O", finishedJob);
     return this;
   }
@@ -50019,7 +50028,7 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     }));
     return channels;
   }
-}, PUBLIC_API_URI, WSS_API_URI, REALTIME_API_URI, SDK_VERSION = "0.35.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.36.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();
@@ -50941,6 +50950,15 @@ var import_debug, __require2, ChangeDifferenceType, KadoaErrorCode, _KadoaSdkExc
     });
     return response.data;
   }
+  async listWorkflowRuns(id, options) {
+    const response = await this.workflowsApi.v4WorkflowsWorkflowIdHistoryGet({
+      workflowId: id,
+      page: options?.page,
+      limit: options?.limit,
+      status: options?.status
+    });
+    return response.data;
+  }
   async delete(id) {
     await this.workflowsApi.v4WorkflowsWorkflowIdDelete({
       workflowId: id
@@ -51703,7 +51721,7 @@ var init_dist2 = __esm(() => {
       return WorkflowsApiFp(this.configuration).v4WorkflowsWorkflowIdGet(requestParameters.workflowId, options).then((request) => request(this.axios, this.basePath));
     }
     v4WorkflowsWorkflowIdHistoryGet(requestParameters, options) {
-      return WorkflowsApiFp(this.configuration).v4WorkflowsWorkflowIdHistoryGet(requestParameters.workflowId, options).then((request) => request(this.axios, this.basePath));
+      return WorkflowsApiFp(this.configuration).v4WorkflowsWorkflowIdHistoryGet(requestParameters.workflowId, requestParameters.page, requestParameters.limit, requestParameters.status, options).then((request) => request(this.axios, this.basePath));
     }
     v4WorkflowsWorkflowIdJobsJobIdGet(requestParameters, options) {
       return WorkflowsApiFp(this.configuration).v4WorkflowsWorkflowIdJobsJobIdGet(requestParameters.workflowId, requestParameters.jobId, options).then((request) => request(this.axios, this.basePath));
@@ -51799,7 +51817,7 @@ This is the main page content.`
   DEFAULT_OPTIONS = {
     mode: "run",
     pollingInterval: 5000,
-    maxWaitTime: 300000,
+    maxWaitTime: 30 * 60 * 1000,
     location: { type: "auto" },
     bypassPreview: true,
     autoStart: true
@@ -52141,6 +52159,22 @@ function deriveStatusLabel(workflow) {
       return ds ?? "Unknown";
   }
 }
+function mapRunStatus(state) {
+  switch (state) {
+    case "FINISHED":
+      return "success";
+    case "IN_PROGRESS":
+    case "VALIDATING":
+      return "in_progress";
+    case "FAILED":
+    case "FAILED_INSUFFICIENT_FUNDS":
+    case "NOT_SUPPORTED":
+      return "failed";
+    default:
+      console.error(`[list_workflow_runs] unmapped run state, passing through verbatim: ${state}`);
+      return state ?? "unknown";
+  }
+}
 function workflowDashboardUrl(workflowId) {
   return `${DASHBOARD_BASE_URL}/workflow/${workflowId}`;
 }
@@ -52364,7 +52398,7 @@ function registerTools(server, ctx, capabilities) {
     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.")
+    schema: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(SchemaFieldShape).strict())).optional().describe("Extraction schema fields. If omitted, the AI agent auto-detects the schema. When you do supply fields, mark the one that identifies a record with isKey — change detection needs it.")
   };
   const webhookAuthShape = exports_external.object({
     type: exports_external.enum(["bearer", "basic", "header"]).describe("Authentication type"),
@@ -52735,6 +52769,35 @@ function registerTools(server, ctx, capabilities) {
       entries
     });
   }));
+  server.registerTool("list_workflow_runs", {
+    description: "List a workflow's execution run history — each run's status, start/finish time, " + "record count, and errors. Use to answer 'when did this last succeed?' " + "(status='success', limit=1) or 'recent success/failure pattern?'. Distinct from " + "get_workflow_history, which is the config audit log. `status` is normally " + "success | failed | in_progress; a run whose backend state this server does not " + "recognize reports that raw state verbatim, so treat any other value as unknown " + "rather than as a failure.",
+    inputSchema: {
+      workflowId: exports_external.string().describe("The workflow ID"),
+      status: exports_external.enum(["success", "failed", "in_progress"]).optional().describe("Filter runs by outcome"),
+      page: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Page number, 1-based (default: 1)"),
+      limit: exports_external.preprocess(coerceNumber(), exports_external.number()).optional().describe("Runs per page (default: 25)")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  }, withErrorHandling("list_workflow_runs", async (args) => {
+    const response = await ctx.client.workflow.listWorkflowRuns(args.workflowId, {
+      page: args.page,
+      limit: args.limit,
+      status: args.status
+    });
+    return jsonResult({
+      workflowId: response.workflowId,
+      runs: (response.workflowRuns ?? []).map((r) => ({
+        id: r.id,
+        status: mapRunStatus(r.state),
+        startedAt: r.startedAt,
+        finishedAt: r.finishedAt,
+        records: r.records,
+        errors: r.errors
+      })),
+      totalCount: response.totalCount,
+      pagination: response.pagination
+    });
+  }));
   server.registerTool("run_workflow", {
     description: "Run a workflow to extract fresh data. The run is asynchronous and may take several minutes. Do NOT poll or sleep-wait for completion. Return the workflow ID to the user and let them check status with get_workflow or fetch results later with fetch_data.",
     inputSchema: {
@@ -52936,13 +52999,15 @@ function registerTools(server, ctx, capabilities) {
   server.registerTool("update_workflow", {
     description: `Update a workflow's configuration. All fields are optional — only provided fields will be updated. Use this to change the name, URLs, extraction schema, entity, prompt, schedule, or other metadata.
 
-` + "IMPORTANT: You cannot change a workflow's interval to or from REAL_TIME. Real-time workflows are architecturally different (Observer service vs Scraper) and must be created as real-time from the start using create_workflow with interval='REAL_TIME'. To switch a workflow between real-time and regular, delete it and create a new one with the correct interval.",
+` + `IMPORTANT: You cannot change a workflow's interval to or from REAL_TIME. Real-time workflows are architecturally different (Observer service vs Scraper) and must be created as real-time from the start using create_workflow with interval='REAL_TIME'. To switch a workflow between real-time and regular, delete it and create a new one with the correct interval.
+
+` + "PROMPT EDITS: `userPrompt` works on most workflows and re-derives the extraction intent. Some agent-built (Shelly) scheduled workflows reject it with `SHELLY_INTENT_REQUIRES_EXTRACTION_SPEC` because their intent is owned elsewhere. " + "If that happens, tell the user to change the extraction intent in Lighthouse chat in the Kadoa dashboard. NEVER delete and recreate the workflow to work around it — that mints a new workflowId, breaking anything downstream keyed to the old one (warehouse tables, connectors) and discarding the workflow's history.",
     inputSchema: strictSchema({
       workflowId: exports_external.string().describe("The workflow ID to update"),
       name: exports_external.string().optional().describe("New name for the workflow"),
       urls: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string()).min(1)).optional().describe("New target URLs for the workflow (array of strings). Also accepts a single URL string."),
       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("New extraction schema fields"),
+      schema: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(SchemaFieldShape).strict())).optional().describe("New extraction schema fields. This REPLACES the whole schema — list every field you want to keep, each with its isKey flag, or the omitted ones and their flags are lost. Call get_workflow first and edit the schema it returns."),
       description: exports_external.string().max(500).optional().describe("Workflow description (max 500 characters)"),
       tags: exports_external.preprocess(coerceArray(true), exports_external.array(exports_external.string())).optional().describe("Tags for organizing workflows"),
       userPrompt: exports_external.string().optional().describe("Navigation prompt for agentic-navigation mode (10-5000 characters)"),
@@ -53409,11 +53474,13 @@ function registerTools(server, ctx, capabilities) {
     });
   }));
   server.registerTool("update_template", {
-    description: "Update a template's name or description. At least one field must be provided.",
+    description: `Update a template's name or description ONLY. At least one of the two must be provided.
+
+` + "This tool CANNOT change what linked workflows inherit — prompt, schema, validation rules, notifications and frequency all live in template *versions*, which are immutable snapshots. " + "To change any of those, publish a new version with `create_template_version` (the version IS the edit), then roll it out to linked workflows with `apply_template_version`. " + "There is no in-place edit of a published version, and never report a prompt or schema change as impossible — versioning is the supported path.",
     inputSchema: strictSchema({
       templateId: exports_external.string().describe("The template ID to update"),
-      name: exports_external.preprocess(coerceNull(), exports_external.string().optional()).describe("New template name"),
-      description: exports_external.preprocess(coerceNull(), exports_external.string().optional()).describe("New template description")
+      name: exports_external.preprocess(coerceNull(), exports_external.string().optional()).optional().describe("New template name"),
+      description: exports_external.preprocess(coerceNull(), exports_external.string().optional()).optional().describe("New template description")
     }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
   }, withErrorHandling("update_template", async (args) => {
@@ -53465,12 +53532,14 @@ function registerTools(server, ctx, capabilities) {
     }))).optional().describe("Predefined categories for a CLASSIFICATION field ({title, definition}[]). Required for fieldType=CLASSIFICATION; omitted otherwise.")
   };
   server.registerTool("create_template_version", {
-    description: "Publish a new version of a template. Versions capture the full workflow config: prompt, schema, and notifications. All fields are optional — include only what this version should set.",
+    description: `Publish a new version of a template. Versions capture the full workflow config: prompt, schema, and notifications. All fields are optional — include only what this version should set.
+
+` + "THIS IS HOW YOU EDIT A TEMPLATE'S PROMPT OR SCHEMA. Published versions are immutable, so 'changing the template prompt' means publishing a new version here and then calling `apply_template_version` to push it onto linked workflows. " + "`update_template` only renames a template; it cannot touch prompt or schema.",
     inputSchema: strictSchema({
       templateId: exports_external.string().describe("The template ID to publish a version for"),
       prompt: exports_external.string().optional().describe("User prompt to copy into workflow config"),
       schemaId: exports_external.string().optional().describe("Existing schema ID to reference (mutually exclusive with schemaFields)"),
-      schemaFields: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(TemplateSchemaFieldShape))).optional().describe("Inline schema fields to create a new schema (mutually exclusive with schemaId)"),
+      schemaFields: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object(TemplateSchemaFieldShape).strict())).optional().describe("Inline schema fields to create a new schema (mutually exclusive with schemaId)"),
       schemaEntity: exports_external.string().optional().describe("Entity name for the inline schema"),
       schemaValidationRules: exports_external.preprocess(coerceJson(), exports_external.record(exports_external.string(), exports_external.record(exports_external.string(), exports_external.unknown()))).optional().describe("Per-field schema validation rules, keyed by field name. Not inherited from prior versions — omitting this on a new version drops any rules the previous version had."),
       notifications: exports_external.preprocess(coerceArray(), exports_external.array(exports_external.object({
@@ -53640,9 +53709,7 @@ var init_tools = __esm(() => {
     description: exports_external.string().optional().describe("What this field contains"),
     example: exports_external.string().describe("Example value"),
     dataType: exports_external.enum(["STRING", "NUMBER", "BOOLEAN", "DATE", "DATETIME", "MONEY", "IMAGE", "LINK", "OBJECT", "ARRAY"]).optional().describe("Data type for the field"),
-    isPrimaryKey: exports_external.boolean().optional(),
-    isRequired: exports_external.boolean().optional(),
-    isUnique: exports_external.boolean().optional()
+    isKey: exports_external.preprocess(coerceBoolean(), exports_external.boolean()).optional().describe("Marks this field as a key field — the stable identity used to match records across runs. Change detection diffs records by their key fields, so a monitored or real-time workflow without one cannot tell an updated record from a new one. Set it on whatever uniquely identifies a row (a detail URL, an ID, a ticker).")
   };
   WORKFLOW_AUDIT_WATCHED_KEYS = [
     "name",
@@ -53662,7 +53729,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@kadoa/mcp",
-    version: "0.5.14",
+    version: "0.5.16",
     description: "Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients",
     type: "module",
     main: "dist/index.js",
@@ -53686,7 +53753,7 @@ var init_package = __esm(() => {
       prepublishOnly: "bun run check-types && bun run test:unit && bun run build"
     },
     dependencies: {
-      "@kadoa/node-sdk": "^0.35.0",
+      "@kadoa/node-sdk": "^0.36.0",
       "@modelcontextprotocol/sdk": "^1.26.0",
       express: "^5.2.1",
       "express-rate-limit": "^8.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadoa/mcp",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "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.35.0",
+    "@kadoa/node-sdk": "^0.36.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "express": "^5.2.1",
     "express-rate-limit": "^8.2.1",