n8n-mcp 2.66.2 → 2.67.0

package/dist/mcp/handlers-n8n-manager.js

@@ -57,6 +57,8 @@ exports.handleDeleteExecution = handleDeleteExecution;
 exports.handleListTestRuns = handleListTestRuns;
 exports.handleGetTestRun = handleGetTestRun;
 exports.handleListTestCases = handleListTestCases;
+exports.handleTriggerTestRun = handleTriggerTestRun;
+exports.handleCancelTestRun = handleCancelTestRun;
 exports.handleHealthCheck = handleHealthCheck;
 exports.handleDiagnostic = handleDiagnostic;
 exports.handleWorkflowVersions = handleWorkflowVersions;
@@ -87,6 +89,7 @@ const n8n_api_1 = require("../config/n8n-api");
 const n8n_api_2 = require("../types/n8n-api");
 const n8n_validation_1 = require("../services/n8n-validation");
 const node_groups_1 = require("../services/node-groups");
+const n8n_version_1 = require("../services/n8n-version");
 const n8n_errors_1 = require("../utils/n8n-errors");
 const logger_1 = require("../utils/logger");
 const zod_1 = require("zod");
@@ -304,22 +307,30 @@ const listExecutionsSchema = zod_1.z.object({
     status: optionalEmptyAware(zod_1.z.enum(['success', 'error', 'waiting'])),
     includeData: zod_1.z.boolean().optional(),
 });
+const testRunPathId = zod_1.z.string().trim().min(1);
 const listTestRunsSchema = zod_1.z.object({
-    workflowId: zod_1.z.string(),
+    workflowId: testRunPathId,
     status: optionalEmptyAware(zod_1.z.enum(['new', 'running', 'completed', 'error', 'cancelled'])),
     limit: zod_1.z.number().min(1).max(250).optional(),
     cursor: optionalEmptyAware(zod_1.z.string()),
 });
 const getTestRunSchema = zod_1.z.object({
-    workflowId: zod_1.z.string(),
-    runId: zod_1.z.string(),
+    workflowId: testRunPathId,
+    runId: testRunPathId,
 });
 const listTestCasesSchema = zod_1.z.object({
-    workflowId: zod_1.z.string(),
-    runId: zod_1.z.string(),
+    workflowId: testRunPathId,
+    runId: testRunPathId,
     limit: zod_1.z.number().min(1).max(250).optional(),
     cursor: optionalEmptyAware(zod_1.z.string()),
 });
+const triggerTestRunSchema = zod_1.z.object({
+    workflowId: testRunPathId,
+});
+const cancelTestRunSchema = zod_1.z.object({
+    workflowId: testRunPathId,
+    runId: testRunPathId,
+});
 const workflowVersionsSchema = zod_1.z.object({
     mode: zod_1.z.enum(['list', 'get', 'rollback', 'delete', 'prune']),
     workflowId: zod_1.z.string().optional(),
@@ -1427,33 +1438,76 @@ async function handleDeleteExecution(args, context) {
         };
     }
 }
-const TEST_RUN_SCOPE_HINT = 'n8n rejected the request (403). The API key lacks testRun scopes - keys created before n8n 2.30 do not have them; re-create the API key on n8n 2.30+. Other causes: evaluations not licensed on this plan, or the key\'s owner lacks access to this workflow.';
-async function handleTestRunError(error, context) {
+const TEST_RUN_QUOTA_HINT = 'n8n rejected the request (402): the plan\'s evaluation quota is used up. It caps how many workflows may have test runs, and this workflow does not hold one of the slots. Re-run a workflow that already has runs, or raise the limit on your n8n plan.';
+function testRunWriteScopeHint(scope) {
+    return `n8n rejected the request (403). The API key lacks the ${scope} scope - that scope only exists on keys created on n8n 2.32+, so re-create the key there. Other causes: evaluations not licensed on this plan, or the key's owner lacks workflow:execute on this workflow.`;
+}
+const TEST_RUN_IDS_HINT = 'Workflow or test run not found. A runId must belong to the given workflowId; check both ids.';
+const TEST_RUN_WORKFLOW_HINT = "Workflow not found. Check the workflowId, and that the API key's owner has access to that workflow.";
+const READ_TEST_RUN_BASE = {
+    minMinor: 30,
+    capability: 'read test runs',
+    scopeHint: 'n8n rejected the request (403). The API key lacks testRun scopes - keys created before n8n 2.30 do not have them; re-create the API key on n8n 2.30+. Other causes: evaluations not licensed on this plan, or the key\'s owner lacks access to this workflow.',
+};
+const LIST_TEST_RUNS_ERRORS = {
+    ...READ_TEST_RUN_BASE,
+    notFoundHint: TEST_RUN_WORKFLOW_HINT,
+};
+const READ_TEST_RUN_ERRORS = {
+    ...READ_TEST_RUN_BASE,
+    notFoundHint: TEST_RUN_IDS_HINT,
+};
+const TRIGGER_TEST_RUN_ERRORS = {
+    minMinor: 32,
+    capability: 'trigger runs from the API',
+    scopeHint: testRunWriteScopeHint('testRun:create'),
+    notFoundHint: TEST_RUN_WORKFLOW_HINT,
+    conflictHint: 'The workflow has no evaluation trigger node. Add an evaluation trigger (n8n-nodes-base.evaluationTrigger) pointing at a dataset, save the workflow, then trigger the run.',
+    postRoute: true,
+};
+const CANCEL_TEST_RUN_ERRORS = {
+    minMinor: 32,
+    capability: 'cancel runs from the API',
+    scopeHint: testRunWriteScopeHint('testRun:cancel'),
+    notFoundHint: TEST_RUN_IDS_HINT,
+    conflictHint: "The test run already finished (status completed, error, or cancelled), so there is nothing to cancel. Use action='get_run' to see its final state.",
+    postRoute: true,
+};
+async function testRunRouteGate(statusCode, context, options) {
+    const client = getN8nApiClient(context);
+    const version = client ? await client.refreshVersion().catch(() => null) : null;
+    if (version) {
+        return (0, n8n_version_1.versionAtLeast)(version, 2, options.minMinor)
+            ? null
+            : `The evaluation API requires n8n 2.${options.minMinor}.0 or later; this instance runs ${version.version}. Upgrade the instance to ${options.capability}.`;
+    }
+    const requirement = `This endpoint requires n8n 2.${options.minMinor}.0 or later, and this instance's n8n version could not be read.`;
+    return statusCode === 405 && options.postRoute
+        ? `${requirement} It rejected POST on the route, which is what an instance predating 2.${options.minMinor}.0 does. Upgrade the instance to ${options.capability}.`
+        : `${requirement} Either the instance predates it, or the request simply did not match. ${options.notFoundHint}`;
+}
+async function handleTestRunError(error, context, options) {
     if (error instanceof zod_1.z.ZodError) {
         return { success: false, error: 'Invalid input', details: { errors: error.errors } };
     }
     if (error instanceof n8n_errors_1.N8nApiError) {
+        if (error.statusCode === 402) {
+            return { success: false, error: TEST_RUN_QUOTA_HINT, code: error.code };
+        }
         if (error.statusCode === 403) {
-            return { success: false, error: TEST_RUN_SCOPE_HINT, code: error.code };
+            return { success: false, error: options.scopeHint, code: error.code };
         }
-        if (error.statusCode === 404) {
-            const client = getN8nApiClient(context);
-            let version = client?.getCachedVersionInfo() ?? null;
-            if (!version && client) {
-                version = await client.getVersion().catch(() => null);
-            }
-            if (version && (version.major < 2 || (version.major === 2 && version.minor < 30))) {
-                return {
-                    success: false,
-                    error: `The evaluation API requires n8n 2.30 or later; this instance runs ${version.version}. Upgrade the instance to read test runs.`,
-                    code: error.code,
-                };
+        if (error.statusCode === 409 && options.conflictHint) {
+            return { success: false, error: options.conflictHint, code: error.code };
+        }
+        if (error.statusCode === 404 || error.statusCode === 405) {
+            const gate = await testRunRouteGate(error.statusCode, context, options);
+            if (gate) {
+                return { success: false, error: gate, code: error.code };
             }
-            return {
-                success: false,
-                error: 'Workflow or test run not found. A runId must belong to the given workflowId; check both ids.',
-                code: error.code,
-            };
+        }
+        if (error.statusCode === 404) {
+            return { success: false, error: options.notFoundHint, code: error.code };
         }
         return { success: false, error: (0, n8n_errors_1.getUserFriendlyErrorMessage)(error), code: error.code };
     }
@@ -1487,7 +1541,7 @@ async function handleListTestRuns(args, context) {
         };
     }
     catch (error) {
-        return handleTestRunError(error, context);
+        return handleTestRunError(error, context, LIST_TEST_RUNS_ERRORS);
     }
 }
 async function handleGetTestRun(args, context) {
@@ -1501,7 +1555,7 @@ async function handleGetTestRun(args, context) {
         };
     }
     catch (error) {
-        return handleTestRunError(error, context);
+        return handleTestRunError(error, context, READ_TEST_RUN_ERRORS);
     }
 }
 async function handleListTestCases(args, context) {
@@ -1526,7 +1580,41 @@ async function handleListTestCases(args, context) {
         };
     }
     catch (error) {
-        return handleTestRunError(error, context);
+        return handleTestRunError(error, context, READ_TEST_RUN_ERRORS);
+    }
+}
+async function handleTriggerTestRun(args, context) {
+    try {
+        const client = ensureApiConfigured(context);
+        const input = triggerTestRunSchema.parse(args || {});
+        const response = await client.triggerTestRun(input.workflowId);
+        return {
+            success: true,
+            data: {
+                ...response,
+                _note: `Run started. Cases execute asynchronously - poll with action='get_run', runId='${response.id}' until status is completed, error, or cancelled.`
+            }
+        };
+    }
+    catch (error) {
+        return handleTestRunError(error, context, TRIGGER_TEST_RUN_ERRORS);
+    }
+}
+async function handleCancelTestRun(args, context) {
+    try {
+        const client = ensureApiConfigured(context);
+        const input = cancelTestRunSchema.parse(args || {});
+        const response = await client.cancelTestRun(input.workflowId, input.runId);
+        return {
+            success: true,
+            data: {
+                ...response,
+                _note: "Cancellation accepted. In-flight cases stop asynchronously - use action='get_run' to confirm the run reached status 'cancelled'."
+            }
+        };
+    }
+    catch (error) {
+        return handleTestRunError(error, context, CANCEL_TEST_RUN_ERRORS);
     }
 }
 async function handleHealthCheck(context) {