n8n-mcp 2.75.0 → 2.76.0

package/dist/mcp/tool-docs/workflow_management/n8n-manage-datatable.js

@@ -5,17 +5,18 @@ exports.n8nManageDatatableDoc = {
     name: 'n8n_manage_datatable',
     category: 'workflow_management',
     essentials: {
-        description: 'Manage n8n data tables and rows. Unified tool for table CRUD and row operations with filtering, pagination, and dry-run support.',
-        keyParameters: ['action', 'tableId', 'name', 'columns', 'data', 'filter'],
+        description: 'Manage n8n data tables, rows and columns. Unified tool for table CRUD, row operations with filtering, pagination and dry-run support, plus column changes on an existing table.',
+        keyParameters: ['action', 'tableId', 'name', 'columns', 'data', 'filter', 'column', 'columnId'],
         example: 'n8n_manage_datatable({action: "createTable", name: "Contacts", columns: [{name: "email", type: "string"}]})',
         performance: 'Fast (100-500ms)',
         tips: [
             'Table actions: createTable, listTables, getTable, updateTable (rename only), deleteTable',
             'Row actions: getRows, insertRows, updateRows, upsertRows, deleteRows',
+            'Column actions: addColumn, deleteColumn, renameColumn - these need N8N_MCP_ACCESS_TOKEN (n8n 2.34+)',
             'Use dryRun: true to preview update/upsert/delete before applying',
             'Filter supports: eq, neq, like, ilike, gt, gte, lt, lte conditions',
             'Use returnData: true to get affected rows back from update/upsert/delete',
-            'Requires N8N_API_URL and N8N_API_KEY configured'
+            'Requires N8N_API_URL and N8N_API_KEY configured; the column actions additionally need N8N_MCP_ACCESS_TOKEN'
         ]
     },
     full: {
@@ -23,7 +24,7 @@ exports.n8nManageDatatableDoc = {
 - **createTable**: Create a new data table with one or more typed columns (columns are required)
 - **listTables**: List all data tables (paginated)
 - **getTable**: Get table details and column definitions by ID
-- **updateTable**: Rename an existing table (name only — column modifications not supported via API)
+- **updateTable**: Rename an existing table (name only — see the column actions below to change columns)
 - **deleteTable**: Permanently delete a table and all its rows
 
 **Row Actions:**
@@ -33,6 +34,15 @@ exports.n8nManageDatatableDoc = {
 - **upsertRows**: Update matching row or insert if none match
 - **deleteRows**: Delete rows matching a filter condition (filter required)
 
+**Column Actions** (routed to n8n's own MCP server - need N8N_MCP_ACCESS_TOKEN and n8n 2.34+):
+- **addColumn**: Add a typed column to an existing table
+- **deleteColumn**: Remove a column and its values (columnId from getTable)
+- **renameColumn**: Rename an existing column
+
+Column names must start with a letter, contain only letters, digits and underscores, and be at most 63 characters; the type is one of string, number, boolean, date. Renaming a TABLE is not a column action - use updateTable, which goes through the public API.
+
+**projectId for column actions:** the official server addresses a table by project. When the instance has exactly one accessible project, it is used automatically; when several are accessible the call returns PROJECT_REQUIRED and lists the candidates, and when none can be resolved it returns PROJECT_REQUIRED asking for an explicit projectId. Pass projectId to skip resolution entirely (list them with n8n_list_catalog({kind: "projects"})).
+
 **Filter System:** Used in getRows, updateRows, upsertRows, deleteRows
 - Combine conditions with "and" (default) or "or"
 - Conditions: eq, neq, like, ilike, gt, gte, lt, lte
@@ -53,6 +63,10 @@ exports.n8nManageDatatableDoc = {
             returnType: { type: 'string', required: false, description: 'For insertRows: "count" (default), "id", or "all"' },
             returnData: { type: 'boolean', required: false, description: 'For updateRows/upsertRows/deleteRows: return affected rows (default: false)' },
             dryRun: { type: 'boolean', required: false, description: 'For updateRows/upsertRows/deleteRows: preview without applying (default: false)' },
+            projectId: { type: 'string', required: false, description: 'For createTable: project to create the table in. For the column actions: project owning the table - auto-resolved when exactly one project is accessible' },
+            column: { type: 'object', required: false, description: 'For addColumn: {name, type} - name must match ^[a-zA-Z][a-zA-Z0-9_]*$ and be at most 63 characters; type is string, number, boolean or date' },
+            columnId: { type: 'string', required: false, description: 'For deleteColumn/renameColumn: ID of the column (read it from getTable)' },
+            timeoutMs: { type: 'integer', required: false, description: 'For the column actions: client timeout in ms (5000-600000, default 30000)' },
         },
         returns: `Depends on action:
 - createTable: {id, name}
@@ -64,7 +78,8 @@ exports.n8nManageDatatableDoc = {
 - insertRows: Depends on returnType (count/ids/rows)
 - updateRows: Update result with optional rows
 - upsertRows: Upsert result with action type
-- deleteRows: Delete result with optional rows`,
+- deleteRows: Delete result with optional rows
+- addColumn/deleteColumn/renameColumn: {success, action, backend: "official-mcp", data} - data is n8n's own answer ({success, message, column?})`,
         examples: [
             '// Create a table\nn8n_manage_datatable({action: "createTable", name: "Contacts", columns: [{name: "email", type: "string"}, {name: "score", type: "number"}]})',
             '// List all tables\nn8n_manage_datatable({action: "listTables"})',
@@ -77,6 +92,9 @@ exports.n8nManageDatatableDoc = {
             '// Update rows (dry run)\nn8n_manage_datatable({action: "updateRows", tableId: "dt-123", filter: {filters: [{columnName: "score", condition: "lt", value: 5}]}, data: {status: "inactive"}, dryRun: true})',
             '// Upsert a row\nn8n_manage_datatable({action: "upsertRows", tableId: "dt-123", filter: {filters: [{columnName: "email", condition: "eq", value: "a@b.com"}]}, data: {score: 15}, returnData: true})',
             '// Delete rows\nn8n_manage_datatable({action: "deleteRows", tableId: "dt-123", filter: {filters: [{columnName: "status", condition: "eq", value: "deleted"}]}})',
+            '// Add a column to an existing table\nn8n_manage_datatable({action: "addColumn", tableId: "dt-123", column: {name: "score", type: "number"}})',
+            '// Rename a column (columnId from getTable)\nn8n_manage_datatable({action: "renameColumn", tableId: "dt-123", columnId: "col-7", name: "total_score"})',
+            '// Delete a column on a multi-project instance\nn8n_manage_datatable({action: "deleteColumn", tableId: "dt-123", columnId: "col-7", projectId: "proj-1"})',
         ],
         useCases: [
             'Persist structured workflow data across executions',
@@ -86,6 +104,7 @@ exports.n8nManageDatatableDoc = {
             'Upsert to maintain unique records by key column',
             'Clean up old or invalid rows with filtered delete',
             'Preview changes with dryRun before modifying data',
+            'Adjust a table schema after creation (add, rename or drop a column)',
         ],
         performance: 'Table operations: 50-300ms. Row operations: 100-500ms depending on data size and filters.',
         bestPractices: [
@@ -95,15 +114,18 @@ exports.n8nManageDatatableDoc = {
             'Use filter with specific conditions to avoid unintended bulk operations',
             'Use cursor-based pagination for large result sets',
             'Use sortBy for deterministic row ordering',
+            'Read columnId from getTable before deleteColumn or renameColumn',
+            'Pass projectId for the column actions on instances with several projects',
         ],
         pitfalls: [
             'deleteTable permanently deletes all rows — cannot be undone',
             'deleteRows requires a filter — cannot delete all rows without one',
-            'Column types cannot be changed after table creation via API',
-            'updateTable can only rename the table (no column modifications via public API)',
-            'createTable requires at least one column — schema cannot be changed after creation',
+            'A column type cannot be changed after the column is created — drop and re-add the column instead',
+            'updateTable only renames the table; use addColumn/deleteColumn/renameColumn to change columns',
+            'The column actions are unavailable without N8N_MCP_ACCESS_TOKEN (NOT_CONFIGURED) or on n8n below 2.34 (OFFICIAL_MCP_TOOL_UNAVAILABLE)',
+            'deleteColumn drops the column values along with the column',
         ],
-        relatedTools: ['n8n_create_workflow', 'n8n_list_workflows', 'n8n_health_check'],
+        relatedTools: ['n8n_create_workflow', 'n8n_list_workflows', 'n8n_list_catalog', 'n8n_health_check'],
     },
 };
 //# sourceMappingURL=n8n-manage-datatable.js.map

package/dist/mcp/tool-docs/workflow_management/n8n-manage-datatable.js.map

@@ -1 +1 @@
-{"version":3,"file":"n8n-manage-datatable.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-manage-datatable.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"n8n-manage-datatable.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-manage-datatable.ts"],"names":[],"mappings":";;;AAEa,QAAA,qBAAqB,GAAsB;IACtD,IAAI,EAAE,sBAAsB;IAC5B,QAAQ,EAAE,qBAAqB;IAC/B,UAAU,EAAE;QACV,WAAW,EAAE,iLAAiL;QAC9L,aAAa,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC;QAC/F,OAAO,EAAE,6GAA6G;QACtH,WAAW,EAAE,kBAAkB;QAC/B,IAAI,EAAE;YACJ,0FAA0F;YAC1F,sEAAsE;YACtE,qGAAqG;YACrG,kEAAkE;YAClE,oEAAoE;YACpE,0EAA0E;YAC1E,4GAA4G;SAC7G;KACF;IACD,IAAI,EAAE;QACJ,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;mHA4BkG;QAC/G,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE;YAC/E,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,oEAAoE,EAAE;YAC/H,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,yCAAyC,EAAE;YACjG,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,oHAAoH,EAAE;YAC9K,IAAI,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,4FAA4F,EAAE;YAC1J,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,wEAAwE,EAAE;YAClI,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,6CAA6C,EAAE;YACtG,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,2CAA2C,EAAE;YACrG,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,oDAAoD,EAAE;YAC9G,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,qDAAqD,EAAE;YAC/G,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,mDAAmD,EAAE;YACjH,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,6EAA6E,EAAE;YAC5I,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,iFAAiF,EAAE;YAC5I,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,0JAA0J,EAAE;YACvN,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,6IAA6I,EAAE;YACvM,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,yEAAyE,EAAE;YACrI,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,2EAA2E,EAAE;SAC1I;QACD,OAAO,EAAE;;;;;;;;;;;iJAWoI;QAC7I,QAAQ,EAAE;YACR,iKAAiK;YACjK,kEAAkE;YAClE,qFAAqF;YACrF,uGAAuG;YACvG,qFAAqF;YACrF,iLAAiL;YACjL,kHAAkH;YAClH,2IAA2I;YAC3I,4MAA4M;YAC5M,sMAAsM;YACtM,iKAAiK;YACjK,+IAA+I;YAC/I,wJAAwJ;YACxJ,2JAA2J;SAC5J;QACD,QAAQ,EAAE;YACR,oDAAoD;YACpD,kDAAkD;YAClD,gDAAgD;YAChD,gDAAgD;YAChD,iDAAiD;YACjD,mDAAmD;YACnD,mDAAmD;YACnD,qEAAqE;SACtE;QACD,WAAW,EAAE,2FAA2F;QACxG,aAAa,EAAE;YACb,oDAAoD;YACpD,2EAA2E;YAC3E,4EAA4E;YAC5E,yEAAyE;YACzE,mDAAmD;YACnD,2CAA2C;YAC3C,iEAAiE;YACjE,0EAA0E;SAC3E;QACD,QAAQ,EAAE;YACR,6DAA6D;YAC7D,mEAAmE;YACnE,kGAAkG;YAClG,+FAA+F;YAC/F,uIAAuI;YACvI,4DAA4D;SAC7D;QACD,YAAY,EAAE,CAAC,qBAAqB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,kBAAkB,CAAC;KACpG;CACF,CAAC"}

package/dist/mcp/tool-docs/workflow_management/n8n-test-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"n8n-test-workflow.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-test-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,kBAAkB,EAAE,iBAuIhC,CAAC"}
+{"version":3,"file":"n8n-test-workflow.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-test-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,kBAAkB,EAAE,iBAgNhC,CAAC"}

package/dist/mcp/tool-docs/workflow_management/n8n-test-workflow.js

@@ -5,34 +5,62 @@ exports.n8nTestWorkflowDoc = {
     name: 'n8n_test_workflow',
     category: 'workflow_management',
     essentials: {
-        description: 'Test/trigger workflow execution. Auto-detects trigger type (webhook/form/chat). Only workflows with these triggers can be executed externally.',
-        keyParameters: ['workflowId', 'triggerType', 'data', 'message'],
+        description: 'Run a workflow. method=auto (default) triggers it over HTTP via its webhook/form/chat trigger; method=prepare/pinned/direct run it through n8n\'s own MCP server.',
+        keyParameters: ['workflowId', 'method', 'data', 'message', 'pinData'],
         example: 'n8n_test_workflow({workflowId: "123"}) - auto-detect trigger',
         performance: 'Immediate trigger, response time depends on workflow complexity',
         tips: [
             'Auto-detects trigger type from workflow if not specified',
-            'Workflow must have a webhook, form, or chat trigger to be executable',
+            'Workflows without a webhook/form/chat trigger need method=direct or method=pinned',
+            'method=prepare first, then method=pinned with the pinData you built from it',
             'For chat triggers, message is required',
-            'All trigger types require the workflow to be ACTIVE'
+            'HTTP trigger types require the workflow to be ACTIVE'
         ]
     },
     full: {
-        description: `Test and trigger n8n workflows through HTTP-based methods. This unified tool supports multiple trigger types:
+        description: `Run an n8n workflow, either over HTTP through its own trigger or through n8n's instance-level MCP server.
 
-**Trigger Types:**
+**Methods (\`method\` parameter):**
+
+| method | backend | What it does |
+|---|---|---|
+| \`auto\` (default) | Public API | Detects a webhook/form/chat trigger and triggers it over HTTP. Without such a trigger it reports that the workflow cannot be triggered externally and names the official methods. It never runs anything through n8n's MCP server. |
+| \`trigger\` | Public API | The same HTTP path, requested explicitly. Detection, the trigger types below and the error when no trigger exists are identical to \`auto\`. |
+| \`prepare\` | n8n MCP server | Read-only: lists the nodes that need pinned data and the schemas n8n can generate for them. Build \`pinData\` from this. |
+| \`pinned\` | n8n MCP server | Runs the workflow with \`pinData\` standing in for trigger, credentialed and HTTP Request nodes, and waits for the run to finish. Every other node still executes for real. |
+| \`direct\` | n8n MCP server | Starts a run with optional \`inputs\` and returns as soon as it has started. Nothing is pinned — every node runs. |
+
+**Trigger types (HTTP path):**
 - **webhook**: HTTP-based triggers (GET/POST/PUT/DELETE)
 - **form**: Form submission triggers
 - **chat**: AI chat triggers with conversation support
 
-**Important:** n8n's public API does not support direct workflow execution. Only workflows with webhook, form, or chat triggers can be executed externally. Workflows with schedule, manual, or other trigger types cannot be triggered via this API.
+n8n's public API does not support direct workflow execution, which is why \`prepare\`/\`pinned\`/\`direct\` go through n8n's own MCP server instead. Those three need \`N8N_MCP_ACCESS_TOKEN\` (n8n 2.34+).
+
+**Consent: "Available in MCP".** n8n refuses MCP calls for a workflow whose "Available in MCP" setting is off, and this tool returns \`WORKFLOW_NOT_EXPOSED\` rather than changing it. Re-run with \`exposeToMcp: true\` to enable it — a visible, persistent setting on the workflow, so confirm with the user first. This flow only ever turns the setting on - disabling it again is a deliberate \`updateSettings\` write (\`availableInMCP: false\`) or a change in the n8n UI. A response that enabled it carries \`exposedToMcp: true\`. In a per-request (multi-tenant or header-driven) deployment, every method except a plain \`prepare\` (the HTTP trigger path, the \`pinned\`/\`direct\` trigger lookup and the \`exposeToMcp\` write all read or write through the Public API) needs the Public API key (\`x-n8n-key\`) for the same instance as \`x-n8n-url\` — without it the call returns \`NOT_CONFIGURED\` rather than acting against a different instance.
+
+**Both run methods can cause real side effects.** \`direct\` runs every node, so any node that calls an external service calls it for real. \`pinned\` pins only trigger nodes, nodes with credentials and HTTP Request nodes; everything else — Code, Set, If, and credential-free I/O such as Execute Command or file read/write — executes normally. Treat both as live runs and confirm with the user before running a workflow that writes anywhere.
+
+**executionMode: production.** \`method: direct\` runs as a manual execution unless you explicitly pass \`executionMode: 'production'\`. That changes the execution context, not whether the run has side effects: a production run uses the production execution path and shows up as one in n8n's execution list. It is never chosen for you.
+
+**Typical sequence for a workflow with no external trigger:**
+1. \`{workflowId, method: 'prepare'}\` — see which nodes need pinned data.
+2. Build sample items per node name (\`{"Webhook": [{"json": {...}}]}\`).
+3. \`{workflowId, method: 'pinned', pinData}\` — run it and read the result.
 
-The tool auto-detects the appropriate trigger type by analyzing the workflow's trigger node. You can override this with the triggerType parameter.`,
+Every response states \`method\` and \`backend\` ('public-api' or 'official-mcp').`,
         parameters: {
             workflowId: {
                 type: 'string',
                 required: true,
                 description: 'Workflow ID to execute'
             },
+            method: {
+                type: 'string',
+                required: false,
+                enum: ['auto', 'trigger', 'prepare', 'pinned', 'direct'],
+                description: 'How to run the workflow (default: auto). See the methods table above.'
+            },
             triggerType: {
                 type: 'string',
                 required: false,
@@ -73,31 +101,66 @@ The tool auto-detects the appropriate trigger type by analyzing the workflow's t
             timeout: {
                 type: 'number',
                 required: false,
-                description: 'Timeout in ms (default: 120000)'
+                description: 'Timeout in ms (default: 120000). HTTP trigger path only (method auto/trigger) — the official methods (prepare/pinned/direct) use timeoutMs instead.'
             },
             waitForResponse: {
                 type: 'boolean',
                 required: false,
                 description: 'Wait for workflow completion (default: true)'
+            },
+            pinData: {
+                type: 'object',
+                required: false,
+                description: 'For method=pinned (required, non-empty): pinned trigger data keyed by node name. Each value is an array of ITEMS, and every item must be wrapped as { "json": { ... } } - e.g. {"Webhook": [{"json": {"id": "123"}}]}, never a flat object. Build it from method=prepare.'
+            },
+            triggerNodeName: {
+                type: 'string',
+                required: false,
+                description: 'For method=pinned/direct: which trigger node to start from. Defaults to the detected trigger node; n8n requires it whenever inputs are given.'
+            },
+            executionMode: {
+                type: 'string',
+                required: false,
+                enum: ['manual', 'production'],
+                description: 'For method=direct: manual (default) or production. Production runs have real side effects and are never chosen implicitly.'
+            },
+            exposeToMcp: {
+                type: 'boolean',
+                required: false,
+                description: 'For the official methods: enable the workflow\'s persistent "Available in MCP" setting when n8n refuses the call. Confirm with the user first.'
+            },
+            timeoutMs: {
+                type: 'integer',
+                required: false,
+                description: 'Client-side deadline for the official call, 5000-600000 (default: 30000 for prepare, 300000 for pinned/direct)'
             }
         },
         returns: `Execution response including:
 - success: boolean
-- data: workflow output data
+- method: which method ran ('trigger', 'prepare', 'pinned', 'direct')
+- backend: 'public-api' or 'official-mcp'
+- data: workflow output data (or the official tool's payload)
 - executionId: for tracking/debugging
-- triggerType: detected or specified trigger type
-- metadata: timing and request details`,
+- triggerType: detected or specified trigger type (HTTP path)
+- metadata: timing and request details
+- exposedToMcp: true when the call enabled "Available in MCP" on the workflow`,
         examples: [
             'n8n_test_workflow({workflowId: "123"}) - Auto-detect and trigger',
             'n8n_test_workflow({workflowId: "123", triggerType: "webhook", data: {name: "John"}}) - Webhook with data',
             'n8n_test_workflow({workflowId: "123", triggerType: "chat", message: "Hello AI"}) - Chat trigger',
-            'n8n_test_workflow({workflowId: "123", triggerType: "form", data: {email: "test@example.com"}}) - Form submission'
+            'n8n_test_workflow({workflowId: "123", triggerType: "form", data: {email: "test@example.com"}}) - Form submission',
+            'n8n_test_workflow({workflowId: "123", method: "prepare"}) - Which nodes need pinned data',
+            'n8n_test_workflow({workflowId: "123", method: "pinned", pinData: {Webhook: [{json: {name: "John"}}]}}) - Run with pinned trigger data',
+            'n8n_test_workflow({workflowId: "123", method: "direct", message: "Hello"}) - Start a manual run through n8n\'s MCP server',
+            'n8n_test_workflow({workflowId: "123", method: "prepare", exposeToMcp: true}) - Enable "Available in MCP" first (confirm with the user)'
         ],
         useCases: [
             'Test workflows during development',
             'Trigger AI chat workflows with messages',
             'Submit form data to form-triggered workflows',
-            'Integrate n8n workflows with external systems via webhooks'
+            'Integrate n8n workflows with external systems via webhooks',
+            'Run a workflow that has no webhook/form/chat trigger (schedule, manual, sub-workflow)',
+            'Exercise a workflow with pinned trigger data instead of a live request'
         ],
         performance: `Performance varies based on workflow complexity and waitForResponse setting:
 - Webhook: Immediate trigger, depends on workflow
@@ -115,8 +178,12 @@ When execution fails, the response includes guidance for debugging:
 
 **Common Errors:**
 - "Workflow not found" - Check workflow ID exists
-- "Workflow not active" - Activate workflow (required for all trigger types)
-- "Workflow cannot be triggered externally" - Workflow has no webhook/form/chat trigger
+- "Workflow not active" - Activate workflow (HTTP trigger path only; pinned/direct run inactive workflows)
+- "Workflow cannot be triggered externally" - Workflow has no webhook/form/chat trigger; use method=direct or method=pinned
+- WORKFLOW_NOT_EXPOSED - The workflow's "Available in MCP" setting is off; re-run with exposeToMcp: true after confirming with the user
+- EXECUTION_FAILED - method=pinned started the run and it ended in error/crashed/canceled; the executionId is on the response
+- OFFICIAL_MCP_TOOL_UNAVAILABLE - This n8n version does not expose the tool (the message names the minimum version)
+- NOT_CONFIGURED - The official methods need N8N_MCP_ACCESS_TOKEN
 - "Chat message required" - Provide message parameter for chat triggers
 - "SSRF protection" - URL validation failed`,
         bestPractices: [
@@ -125,11 +192,17 @@ When execution fails, the response includes guidance for debugging:
             'For chat workflows, provide sessionId for multi-turn conversations',
             'Use mode="preview" with n8n_executions for efficient debugging',
             'Test with small data payloads first',
-            'Activate workflows before testing (use n8n_update_partial_workflow with activateWorkflow)'
+            'Activate workflows before testing (use n8n_update_partial_workflow with activateWorkflow)',
+            'Run method=prepare before method=pinned so pinData matches the nodes n8n expects',
+            'Keep method=direct on executionMode manual unless a production run is genuinely wanted',
+            'Confirm with the user before passing exposeToMcp: true - it changes a visible workflow setting'
         ],
         pitfalls: [
-            'All trigger types require the workflow to be ACTIVE',
-            'Workflows without webhook/form/chat triggers cannot be executed externally',
+            'method=auto never runs a workflow through n8n\'s MCP server - it reports the workflow cannot be triggered instead',
+            'method=direct returns as soon as the run starts; poll n8n_executions with the executionId for the outcome',
+            'executionMode: production runs the workflow for real',
+            'All HTTP trigger types require the workflow to be ACTIVE',
+            'Workflows without webhook/form/chat triggers cannot be triggered over HTTP - run them with method=pinned or method=direct instead',
             'Chat trigger requires message parameter',
             'Form data must match expected form fields',
             'Webhook method must match node configuration'

package/dist/mcp/tool-docs/workflow_management/n8n-test-workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"n8n-test-workflow.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-test-workflow.ts"],"names":[],"mappings":";;;AAEa,QAAA,kBAAkB,GAAsB;IACnD,IAAI,EAAE,mBAAmB;IACzB,QAAQ,EAAE,qBAAqB;IAC/B,UAAU,EAAE;QACV,WAAW,EAAE,gJAAgJ;QAC7J,aAAa,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC;QAC/D,OAAO,EAAE,8DAA8D;QACvE,WAAW,EAAE,iEAAiE;QAC9E,IAAI,EAAE;YACJ,0DAA0D;YAC1D,sEAAsE;YACtE,wCAAwC;YACxC,qDAAqD;SACtD;KACF;IACD,IAAI,EAAE;QACJ,WAAW,EAAE;;;;;;;;;mJASkI;QAC/I,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,wBAAwB;aACtC;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;gBACjC,WAAW,EAAE,yFAAyF;aACvG;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;gBACtC,WAAW,EAAE,kEAAkE;aAChF;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,wCAAwC;aACtD;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,wDAAwD;aACtE;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,kDAAkD;aAChE;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,+CAA+C;aAC7D;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,qBAAqB;aACnC;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,iCAAiC;aAC/C;YACD,eAAe,EAAE;gBACf,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,8CAA8C;aAC5D;SACF;QACD,OAAO,EAAE;;;;;uCAK0B;QACnC,QAAQ,EAAE;YACR,kEAAkE;YAClE,0GAA0G;YAC1G,iGAAiG;YACjG,kHAAkH;SACnH;QACD,QAAQ,EAAE;YACR,mCAAmC;YACnC,yCAAyC;YACzC,8CAA8C;YAC9C,4DAA4D;SAC7D;QACD,WAAW,EAAE;;;+CAG8B;QAC3C,aAAa,EAAE;;;;;;;;;;;;;;;4CAeyB;QACxC,aAAa,EAAE;YACb,0DAA0D;YAC1D,qEAAqE;YACrE,oEAAoE;YACpE,gEAAgE;YAChE,qCAAqC;YACrC,2FAA2F;SAC5F;QACD,QAAQ,EAAE;YACR,qDAAqD;YACrD,4EAA4E;YAC5E,yCAAyC;YACzC,2CAA2C;YAC3C,8CAA8C;SAC/C;QACD,YAAY,EAAE,CAAC,gBAAgB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,uBAAuB,CAAC;KACrG;CACF,CAAC"}
+{"version":3,"file":"n8n-test-workflow.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-test-workflow.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tool-docs/workflow_management/n8n-workflow-versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"n8n-workflow-versions.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,sBAAsB,EAAE,iBAyJpC,CAAC"}
+{"version":3,"file":"n8n-workflow-versions.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,sBAAsB,EAAE,iBA8PpC,CAAC"}

package/dist/mcp/tool-docs/workflow_management/n8n-workflow-versions.js

@@ -5,20 +5,65 @@ exports.n8nWorkflowVersionsDoc = {
     name: 'n8n_workflow_versions',
     category: 'workflow_management',
     essentials: {
-        description: 'Manage workflow version history, rollback to previous versions, and cleanup old versions',
-        keyParameters: ['mode', 'workflowId', 'versionId'],
+        description: 'Manage workflow version history: list, get, diff, roll back and clean up, from n8n-mcp snapshots (local) or n8n\'s own history (native)',
+        keyParameters: ['mode', 'source', 'workflowId', 'versionId'],
         example: 'n8n_workflow_versions({mode: "list", workflowId: "abc123"})',
-        performance: 'Fast for list/get (~100ms), moderate for rollback (~200-500ms)',
+        performance: 'Fast for list/get (~100ms), moderate for rollback (~200-500ms); native modes add one round-trip to n8n\'s MCP server',
         tips: [
             'Use mode="list" to see all saved versions before rollback',
-            'Rollback creates a backup version automatically',
-            'Use prune to clean up old versions and save storage',
+            'source="local" (default) only sees changes n8n-mcp made; source="native" also sees UI edits',
+            'Rollback creates a backup version automatically (local only)',
+            'Use prune to clean up old versions and save storage (local only)',
             'Versions are scoped to your n8n instance; you only ever see your own',
             'Old backups are pruned automatically (10 per workflow + an age-based retention window)'
         ]
     },
     full: {
-        description: `Comprehensive workflow version management system. Supports five operations:
+        description: `Workflow version management over two independent histories.
+
+**source: "local"** (default) - the snapshots n8n-mcp writes before it changes a workflow. Numbered
+per workflow, scoped to your n8n instance, available on any n8n version, and blind to anything that
+did not go through n8n-mcp (a person editing the workflow in the n8n UI leaves no local snapshot).
+This is the only source that supports delete and prune.
+
+**source: "native"** - n8n's own workflow history, the same list the n8n UI shows, read through the
+instance-level MCP server. It covers every change, including UI edits by people, and n8n owns its
+retention, so delete and prune are refused with MODE_NOT_SUPPORTED_FOR_SOURCE. Requires an n8n MCP
+access token (N8N_MCP_ACCESS_TOKEN) and the workflow's "Available in MCP" setting; the version ids
+are opaque strings, not numbers.
+
+Mode by source:
+
+| mode | local | native |
+|------|-------|--------|
+| list | yes | yes (limit capped at 50, offset supported) |
+| get | yes | yes |
+| rollback | yes, optionally validated first | yes, never validated first |
+| diff | yes (format: "n8n-mcp") | yes (format: "n8n") |
+| delete | yes | MODE_NOT_SUPPORTED_FOR_SOURCE |
+| prune | yes | MODE_NOT_SUPPORTED_FOR_SOURCE |
+
+**Diff formats differ by source.** Local diff (\`data.format: "n8n-mcp"\`) reports \`addedNodes\`,
+\`removedNodes\` and \`modifiedNodes\` as node **IDs**, \`connectionChanges\` as 0 or 1, and
+\`settingChanges\` as a before/after settings diff. Native diff (\`data.format: "n8n"\`) is n8n's own
+payload: field-level \`__old\`/\`__new\` values on modified nodes, plus connections added and removed.
+
+**Native rollback is not pre-validated.** n8n's version payload carries only name, type and
+credentials per node - no position, typeVersion or parameters - so there is nothing for the workflow
+validator to check. \`validateBefore\` is accepted and ignored on native, and the response says
+\`validation: "not available for native versions"\`.
+
+**Consent flow for native modes.** If the workflow is not exposed to n8n's MCP server, the call
+returns WORKFLOW_NOT_EXPOSED with a hint. Re-running with \`exposeToMcp: true\` turns on the
+workflow's "Available in MCP" setting and retries once; the response then carries
+\`exposedToMcp: true\`. That setting is visible and persistent in the n8n UI - confirm with the user
+before enabling it. This flow only ever turns the setting on - disabling it again is a deliberate
+\`updateSettings\` write (\`availableInMCP: false\`) or a change in the n8n UI.
+
+Every response states \`mode\`, \`source\` and \`backend\` (\`"n8n-mcp"\` for local, \`"official-mcp"\`
+for native).
+
+Supports six operations:
 
 **list** - Show version history for a workflow
 - Returns all saved versions with timestamps, snapshot sizes, and metadata
@@ -33,45 +78,68 @@ exports.n8nWorkflowVersionsDoc = {
 - Optionally validates the workflow structure before applying
 - Returns the restored workflow and backup version ID
 
-**delete** - Delete specific version(s)
+**diff** - Compare two versions
+- Requires versionId and toVersionId
+- Local: compares two stored snapshots of the same workflow (both must belong to workflowId)
+- Native: returns n8n's own diff between two of its versions
+
+**delete** - Delete specific version(s) (local only)
 - Delete a single version by versionId
 - Delete all versions for a workflow with deleteAll: true
 
 **prune** - Clean up old versions
 - Keeps only the N most recent versions (default: 10)
 - Useful for managing storage and keeping history manageable
+- Local only
 
-All version operations are scoped to your n8n instance — you can only see and act on backups created
-under your own credentials. Old backups are also removed automatically (10 most recent per workflow,
-plus an age-based retention window).`,
+Local version operations are scoped to your n8n instance — you can only see and act on backups
+created under your own credentials. Old local backups are also removed automatically (10 most recent
+per workflow, plus an age-based retention window). Native history retention is n8n's own.`,
         parameters: {
             mode: {
                 type: 'string',
                 required: true,
-                description: 'Operation mode: "list", "get", "rollback", "delete", or "prune"',
-                enum: ['list', 'get', 'rollback', 'delete', 'prune']
+                description: 'Operation mode: "list", "get", "rollback", "diff", "delete", or "prune"',
+                enum: ['list', 'get', 'rollback', 'delete', 'prune', 'diff']
+            },
+            source: {
+                type: 'string',
+                required: false,
+                default: 'local',
+                description: 'Which history to read: "local" (n8n-mcp snapshots) or "native" (n8n\'s own version history). delete and prune are local-only.',
+                enum: ['local', 'native']
             },
             workflowId: {
                 type: 'string',
                 required: false,
-                description: 'Workflow ID (required for list, rollback, delete, prune modes)'
+                description: 'Workflow ID (required for list, rollback, diff, delete, prune modes; required for every native mode)'
             },
             versionId: {
-                type: 'number',
+                type: 'string | number',
+                required: false,
+                description: 'Version ID. local: numeric snapshot id (number or numeric string; anything else is INVALID_ARGS). native: n8n\'s version id string. Required for get and diff, for a single delete, and for native rollback; optional for local rollback.'
+            },
+            toVersionId: {
+                type: 'string | number',
                 required: false,
-                description: 'Version ID (required for get mode, optional for rollback to specific version, required for single delete)'
+                description: 'The second version to compare against in diff mode (same id format as versionId)'
             },
             limit: {
                 type: 'number',
                 required: false,
                 default: 10,
-                description: 'Maximum versions to return in list mode'
+                description: 'Maximum versions to return in list mode (native: capped at 50)'
+            },
+            offset: {
+                type: 'number',
+                required: false,
+                description: 'Skip this many versions in native list mode'
             },
             validateBefore: {
                 type: 'boolean',
                 required: false,
                 default: true,
-                description: 'Validate workflow structure before rollback (rollback mode only)'
+                description: 'Validate workflow structure before rollback (local rollback only; accepted and ignored on native)'
             },
             deleteAll: {
                 type: 'boolean',
@@ -84,6 +152,17 @@ plus an age-based retention window).`,
                 required: false,
                 default: 10,
                 description: 'Keep N most recent versions (prune mode only)'
+            },
+            exposeToMcp: {
+                type: 'boolean',
+                required: false,
+                description: 'Native only. On a WORKFLOW_NOT_EXPOSED refusal, enable the workflow\'s "Available in MCP" setting and retry once. Visible, persistent change - confirm with the user first.'
+            },
+            timeoutMs: {
+                type: 'integer',
+                required: false,
+                default: 30000,
+                description: 'Client deadline for the native call (5000-600000)'
             }
         },
         returns: `Response varies by mode:
@@ -103,9 +182,17 @@ plus an age-based retention window).`,
 **delete mode:**
 - deletedCount: Number of versions deleted
 
+**diff mode:**
+- data.format: "n8n-mcp" (local) or "n8n" (native) - the two payloads are shaped differently
+- local: addedNodes / removedNodes / modifiedNodes (node IDs), connectionChanges (0 or 1), settingChanges, nodeGroupChanges
+- native: nodesAdded / nodesRemoved / nodesModified (with field-level __old/__new), connectionsAdded, connectionsRemoved
+
 **prune mode:**
 - prunedCount: Number of old versions removed
-- remainingCount: Number of versions kept`,
+- remainingCount: Number of versions kept
+
+Every response also carries mode, source and backend ("n8n-mcp" for local, "official-mcp" for native).
+Native rollback additionally carries validation: "not available for native versions".`,
         examples: [
             '// List version history\nn8n_workflow_versions({mode: "list", workflowId: "abc123", limit: 5})',
             '// Get specific version details\nn8n_workflow_versions({mode: "get", versionId: 42})',
@@ -113,7 +200,12 @@ plus an age-based retention window).`,
             '// Rollback to specific version\nn8n_workflow_versions({mode: "rollback", workflowId: "abc123", versionId: 42})',
             '// Delete specific version\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", versionId: 42})',
             '// Delete all versions for workflow\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", deleteAll: true})',
-            '// Prune to keep only 5 most recent\nn8n_workflow_versions({mode: "prune", workflowId: "abc123", maxVersions: 5})'
+            '// Prune to keep only 5 most recent\nn8n_workflow_versions({mode: "prune", workflowId: "abc123", maxVersions: 5})',
+            '// Compare two local snapshots\nn8n_workflow_versions({mode: "diff", workflowId: "abc123", versionId: 41, toVersionId: 42})',
+            '// List n8n\'s own history, including UI edits\nn8n_workflow_versions({mode: "list", source: "native", workflowId: "abc123", limit: 20})',
+            '// Compare two of n8n\'s own versions\nn8n_workflow_versions({mode: "diff", source: "native", workflowId: "abc123", versionId: "v1", toVersionId: "v2"})',
+            '// Restore one of n8n\'s own versions (no pre-validation)\nn8n_workflow_versions({mode: "rollback", source: "native", workflowId: "abc123", versionId: "v1"})',
+            '// Retry after WORKFLOW_NOT_EXPOSED, enabling the setting\nn8n_workflow_versions({mode: "list", source: "native", workflowId: "abc123", exposeToMcp: true})'
         ],
         useCases: [
             'Recover from accidental workflow changes',
@@ -127,16 +219,21 @@ plus an age-based retention window).`,
 - get: Fast (~100ms) - single row retrieval
 - rollback: Moderate (~200-500ms) - includes backup creation and workflow update
 - delete: Fast (~50-100ms) - database delete operation
-- prune: Moderate (~100-300ms) - depends on number of versions to delete`,
-        modeComparison: `| Mode | Required Params | Optional Params | Risk Level |
-|------|-----------------|-----------------|------------|
-| list | workflowId | limit | Low |
-| get | versionId | - | Low |
-| rollback | workflowId | versionId, validateBefore | Medium |
-| delete | workflowId | versionId, deleteAll | High |
-| prune | workflowId | maxVersions | Medium |`,
+- prune: Moderate (~100-300ms) - depends on number of versions to delete
+- diff (local): Fast (~100ms) - two snapshot reads and an in-memory comparison
+- native modes: one round-trip to n8n's MCP server per call (30s client deadline by default), so slower than any local mode`,
+        modeComparison: `| Mode | Required Params | Optional Params | Sources | Risk Level |
+|------|-----------------|-----------------|---------|------------|
+| list | workflowId | limit, offset | local, native | Low |
+| get | versionId (native: + workflowId) | - | local, native | Low |
+| diff | workflowId, versionId, toVersionId | - | local, native | Low |
+| rollback | workflowId | versionId, validateBefore | local, native | Medium |
+| delete | workflowId | versionId, deleteAll | local | High |
+| prune | workflowId | maxVersions | local | Medium |`,
         bestPractices: [
             'Always list versions before rollback to pick the right one',
+            'Use source: "native" when the workflow is also edited in the n8n UI - local snapshots miss those edits',
+            'Read a diff before a rollback so you know what the restore will change',
             'Enable validateBefore for rollback to catch structural issues',
             'Use prune regularly to keep version history manageable',
             'Document why you are rolling back for audit purposes'
@@ -146,7 +243,11 @@ plus an age-based retention window).`,
             'Deleted versions cannot be recovered',
             'Version operations are scoped to your instance - versions from other instances are not visible',
             'Version IDs are sequential but may have gaps after deletes',
-            'Large workflows may have significant version storage overhead'
+            'Large workflows may have significant version storage overhead',
+            'Local and native version ids are different id spaces - a native id will not resolve locally',
+            'Native rollback is not validated before it is applied; n8n\'s version payload lacks the fields the validator needs',
+            'Native delete and prune are refused (MODE_NOT_SUPPORTED_FOR_SOURCE) - n8n owns that retention',
+            'Diff payloads differ by source; branch on data.format rather than assuming field names'
         ],
         relatedTools: [
             'n8n_get_workflow - View current workflow state',

package/dist/mcp/tool-docs/workflow_management/n8n-workflow-versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"n8n-workflow-versions.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts"],"names":[],"mappings":";;;AAEa,QAAA,sBAAsB,GAAsB;IACvD,IAAI,EAAE,uBAAuB;IAC7B,QAAQ,EAAE,qBAAqB;IAC/B,UAAU,EAAE;QACV,WAAW,EAAE,0FAA0F;QACvG,aAAa,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC;QAClD,OAAO,EAAE,6DAA6D;QACtE,WAAW,EAAE,gEAAgE;QAC7E,IAAI,EAAE;YACJ,2DAA2D;YAC3D,iDAAiD;YACjD,qDAAqD;YACrD,sEAAsE;YACtE,wFAAwF;SACzF;KACF;IACD,IAAI,EAAE;QACJ,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;qCAyBoB;QACjC,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,iEAAiE;gBAC9E,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC;aACrD;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,gEAAgE;aAC9E;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,2GAA2G;aACzH;YACD,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,yCAAyC;aACvD;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,kEAAkE;aAChF;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,KAAK;gBACd,WAAW,EAAE,qDAAqD;aACnE;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,+CAA+C;aAC7D;SACF;QACD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;0CAmB6B;QACtC,QAAQ,EAAE;YACR,gGAAgG;YAChG,sFAAsF;YACtF,sGAAsG;YACtG,iHAAiH;YACjH,0GAA0G;YAC1G,qHAAqH;YACrH,mHAAmH;SACpH;QACD,QAAQ,EAAE;YACR,0CAA0C;YAC1C,iDAAiD;YACjD,gDAAgD;YAChD,gDAAgD;YAChD,uCAAuC;SACxC;QACD,WAAW,EAAE;;;;;yEAKwD;QACrE,cAAc,EAAE;;;;;;8CAM0B;QAC1C,aAAa,EAAE;YACb,4DAA4D;YAC5D,+DAA+D;YAC/D,wDAAwD;YACxD,sDAAsD;SACvD;QACD,QAAQ,EAAE;YACR,wEAAwE;YACxE,sCAAsC;YACtC,gGAAgG;YAChG,4DAA4D;YAC5D,+DAA+D;SAChE;QACD,YAAY,EAAE;YACZ,gDAAgD;YAChD,wDAAwD;YACxD,oDAAoD;SACrD;KACF;CACF,CAAC"}
+{"version":3,"file":"n8n-workflow-versions.js","sourceRoot":"","sources":["../../../../src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tool-policy.d.ts

@@ -0,0 +1,9 @@
+export declare function getDisabledTools(): Set<string>;
+export declare function isToolDisabled(toolName: string): boolean;
+export declare function getValidOperations(toolName: string): Set<string>;
+export declare function getDisabledToolOperations(): Map<string, Set<string>>;
+export declare function getDisabledOperations(toolName: string): Set<string>;
+export declare function resolveRequestedOperation(toolName: string, args: any): unknown;
+export declare function isOperationDisabled(toolName: string, operation: string): boolean;
+export declare function resetToolPolicyCache(): void;
+//# sourceMappingURL=tool-policy.d.ts.map

package/dist/mcp/tool-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/mcp/tool-policy.ts"],"names":[],"mappings":"AAmCA,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,CAAC,CA+B9C;AAGD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAcD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAUhE;AAWD,wBAAgB,yBAAyB,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAoEpE;AAGD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEnE;AAeD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAQ9E;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhF;AAGD,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}