n8n-mcp 2.59.3 → 2.60.0

package/.env.example

@@ -122,6 +122,25 @@ AUTH_TOKEN=your-secure-token-here
 # Default: (empty - all tools enabled)
 # DISABLED_TOOLS=
 
+# Per-Operation Tool Filtering
+# Disable specific operations within a tool without losing its read paths.
+# Useful for sensitive deployments that need read-only access
+# to tools that bundle read and write operations under one name.
+#
+# Format: Semicolon-separated list of <tool_name>:<comma_separated_operations>
+# Operation names match the action / mode enum values in each tool's schema.
+#
+# Eligible tools and their operations:
+#   n8n_executions       — action: get, list, delete
+#   n8n_workflow_versions — mode: list, get, rollback, delete, prune
+#
+# Read-only deployment recipe (blocks all destructive operations):
+# DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete
+#
+# Combine with n8n API key RBAC for defence in depth.
+# Default: (empty - all operations enabled)
+# DISABLED_TOOL_OPERATIONS=
+
 # =========================
 # MULTI-TENANT CONFIGURATION
 # =========================

package/README.md

@@ -389,6 +389,22 @@ These tools require `N8N_API_URL` and `N8N_API_KEY` in your configuration.
 #### System Tools
 - **`n8n_health_check`** - Check n8n API connectivity and features
 
+### Read-Only Deployment
+
+For governance-sensitive environments, use both env vars together. Fully disable purely write/destructive tools:
+
+```bash
+DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_generate_workflow,n8n_manage_credentials,n8n_manage_datatable
+```
+
+For tools that bundle read and write operations under one name, block only the destructive operations while keeping `list` and `get`:
+
+```bash
+DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete
+```
+
+Combine with a read-only n8n API key (Settings → API in your n8n instance) for defence in depth. See [Read-Only Deployment Recipe](./docs/HTTP_DEPLOYMENT.md#read-only-deployment-recipe) for the full setup guide.
+
 ## Documentation
 
 - [Self-Hosting Guide](./docs/SELF_HOSTING.md) - npx, Docker, Railway, and local installation

package/dist/mcp/server.d.ts

@@ -19,6 +19,8 @@ export declare class N8NDocumentationMCPServer {
     private previousToolTimestamp;
     private earlyLogger;
     private disabledToolsCache;
+    private disabledToolOperationsCache;
+    private filteredToolDefinitionsCache;
     private useSharedDatabase;
     private sharedDbState;
     private isShutdown;
@@ -36,6 +38,8 @@ export declare class N8NDocumentationMCPServer {
     private dbHealthChecked;
     private validateDatabaseHealth;
     private getDisabledTools;
+    private getDisabledToolOperations;
+    private buildFilteredToolDefinitions;
     private setupHandlers;
     private sanitizeValidationResult;
     private validateToolParams;

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.js

@@ -88,6 +88,8 @@ class N8NDocumentationMCPServer {
         this.previousToolTimestamp = Date.now();
         this.earlyLogger = null;
         this.disabledToolsCache = null;
+        this.disabledToolOperationsCache = null;
+        this.filteredToolDefinitionsCache = null;
         this.useSharedDatabase = false;
         this.sharedDbState = null;
         this.isShutdown = false;
@@ -389,6 +391,102 @@ class N8NDocumentationMCPServer {
         this.disabledToolsCache = new Set(tools);
         return this.disabledToolsCache;
     }
+    getDisabledToolOperations() {
+        if (this.disabledToolOperationsCache !== null) {
+            return this.disabledToolOperationsCache;
+        }
+        const result = new Map();
+        let envVal = process.env.DISABLED_TOOL_OPERATIONS || '';
+        if (!envVal) {
+            this.disabledToolOperationsCache = result;
+            this.filteredToolDefinitionsCache = new Map();
+            return result;
+        }
+        if (envVal.length > 10000) {
+            logger_1.logger.warn(`DISABLED_TOOL_OPERATIONS environment variable too long (${envVal.length} chars), truncating to 10000`);
+            envVal = envVal.substring(0, 10000);
+        }
+        let entries = envVal.split(';').map(e => e.trim()).filter(Boolean);
+        if (entries.length > 50) {
+            logger_1.logger.warn(`DISABLED_TOOL_OPERATIONS contains ${entries.length} entries, limiting to first 50`);
+            entries = entries.slice(0, 50);
+        }
+        for (const entry of entries) {
+            const colonIdx = entry.indexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const toolName = entry.substring(0, colonIdx).trim();
+            const opsStr = entry.substring(colonIdx + 1).trim();
+            if (!toolName || !opsStr)
+                continue;
+            const ops = opsStr.split(',').map(o => o.trim().toLowerCase()).filter(Boolean);
+            if (ops.length === 0)
+                continue;
+            const existing = result.get(toolName) ?? new Set();
+            ops.forEach(op => existing.add(op));
+            result.set(toolName, existing);
+        }
+        for (const [toolName, ops] of result) {
+            const paramName = tools_n8n_manager_1.TOOL_OPERATION_PARAM[toolName];
+            if (!paramName) {
+                logger_1.logger.warn(`DISABLED_TOOL_OPERATIONS: unknown tool '${toolName}' — no per-operation filtering applied. Eligible tools: ${Object.keys(tools_n8n_manager_1.TOOL_OPERATION_PARAM).join(', ')}`);
+                continue;
+            }
+            const tool = tools_n8n_manager_1.n8nManagementTools.find(t => t.name === toolName);
+            const enumValues = tool?.inputSchema?.properties?.[paramName]?.enum ?? [];
+            for (const op of ops) {
+                if (enumValues.length > 0 && !enumValues.includes(op)) {
+                    logger_1.logger.warn(`DISABLED_TOOL_OPERATIONS: '${op}' is not a valid ${paramName} for '${toolName}' (valid: ${enumValues.join(', ')}); it will have no effect.`);
+                }
+            }
+        }
+        if (result.size > 0) {
+            const summary = [...result.entries()]
+                .map(([t, ops]) => `${t}: [${[...ops].join(', ')}]`)
+                .join('; ');
+            logger_1.logger.info(`Disabled tool operations configured: ${summary}`);
+        }
+        this.disabledToolOperationsCache = result;
+        this.filteredToolDefinitionsCache = this.buildFilteredToolDefinitions(result);
+        return result;
+    }
+    buildFilteredToolDefinitions(disabledOps) {
+        const cache = new Map();
+        for (const [toolName, ops] of disabledOps) {
+            const paramName = tools_n8n_manager_1.TOOL_OPERATION_PARAM[toolName];
+            if (!paramName)
+                continue;
+            const original = tools_n8n_manager_1.n8nManagementTools.find(t => t.name === toolName);
+            if (!original)
+                continue;
+            const cloned = JSON.parse(JSON.stringify(original));
+            const param = cloned.inputSchema?.properties?.[paramName];
+            if (param?.enum) {
+                param.enum = param.enum.filter(v => !ops.has(v.toLowerCase()));
+                if (param.enum.length === 0) {
+                    logger_1.logger.warn(`DISABLED_TOOL_OPERATIONS: all operations for '${toolName}' are disabled ` +
+                        `but the tool still appears in ListTools. ` +
+                        `Consider adding '${toolName}' to DISABLED_TOOLS instead.`);
+                }
+                if (param.description) {
+                    const disabledList = [...ops].join(', ');
+                    param.description = `${param.description} (disabled by server policy: ${disabledList})`;
+                }
+            }
+            const disabledList = [...ops].join(', ');
+            cloned.description = `${cloned.description}\n\n> Operations disabled by server policy: ${disabledList}`;
+            const destructive = tools_n8n_manager_1.DESTRUCTIVE_TOOL_OPERATIONS[toolName];
+            if (destructive && cloned.annotations) {
+                const remaining = param?.enum ?? [];
+                const stillDestructive = remaining.some(v => destructive.has(String(v).toLowerCase()));
+                if (!stillDestructive) {
+                    cloned.annotations = { ...cloned.annotations, readOnlyHint: true, destructiveHint: false };
+                }
+            }
+            cache.set(toolName, cloned);
+        }
+        return cache;
+    }
     setupHandlers() {
         this.server.setRequestHandler(types_js_1.InitializeRequestSchema, async (request) => {
             const clientVersion = request.params.protocolVersion;
@@ -471,6 +569,10 @@ class N8NDocumentationMCPServer {
                     description: tool.description
                 });
             });
+            const disabledToolOps = this.getDisabledToolOperations();
+            if (disabledToolOps.size > 0 && this.filteredToolDefinitionsCache) {
+                tools = tools.map(tool => this.filteredToolDefinitionsCache.get(tool.name) ?? tool);
+            }
             ui_1.UIAppRegistry.injectToolMeta(tools);
             return { tools };
         });
@@ -493,7 +595,8 @@ class N8NDocumentationMCPServer {
                                 message: `Tool '${name}' is not available in this deployment. It has been disabled via DISABLED_TOOLS environment variable.`,
                                 tool: name
                             }, null, 2)
-                        }]
+                        }],
+                    isError: true
                 };
             }
             let processedArgs = args;
@@ -542,6 +645,30 @@ class N8NDocumentationMCPServer {
             if (processedArgs) {
                 processedArgs = JSON.parse(JSON.stringify(processedArgs));
             }
+            const disabledToolOps = this.getDisabledToolOperations();
+            const disabledOpsForTool = disabledToolOps.get(name);
+            if (disabledOpsForTool && disabledOpsForTool.size > 0) {
+                const paramName = tools_n8n_manager_1.TOOL_OPERATION_PARAM[name];
+                if (paramName) {
+                    const requestedOp = processedArgs?.[paramName];
+                    if (requestedOp && disabledOpsForTool.has(String(requestedOp).toLowerCase())) {
+                        logger_1.logger.warn(`Attempted to call disabled operation: ${name}.${requestedOp}`);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: 'OPERATION_DISABLED',
+                                        message: `Operation '${requestedOp}' on tool '${name}' is disabled by server policy.`,
+                                        tool: name,
+                                        operation: requestedOp,
+                                        disabledOperations: [...disabledOpsForTool]
+                                    }, null, 2)
+                                }],
+                            isError: true
+                        };
+                    }
+                }
+            }
             const isAdditionalTool = this.additionalToolsByName.has(name);
             try {
                 logger_1.logger.debug(`Executing tool: ${name}`, (0, redaction_1.summarizeToolCallArgs)(processedArgs));
@@ -1008,6 +1135,17 @@ class N8NDocumentationMCPServer {
         if (disabledTools.has(name)) {
             throw new Error(`Tool '${name}' is disabled via DISABLED_TOOLS environment variable`);
         }
+        const disabledToolOps = this.getDisabledToolOperations();
+        const disabledOpsForTool = disabledToolOps.get(name);
+        if (disabledOpsForTool && disabledOpsForTool.size > 0) {
+            const paramName = tools_n8n_manager_1.TOOL_OPERATION_PARAM[name];
+            if (paramName) {
+                const requestedOp = args[paramName];
+                if (requestedOp && disabledOpsForTool.has(String(requestedOp).toLowerCase())) {
+                    throw new Error(`Operation '${requestedOp}' on tool '${name}' is disabled by server policy`);
+                }
+            }
+        }
         logger_1.logger.info(`Tool execution: ${name}`, (0, redaction_1.summarizeToolCallArgs)(args));
         if (typeof args !== 'object' || args === null) {
             throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
@@ -2403,7 +2541,7 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
             totalVersions: versions.length,
             hasVersionHistory: versions.length > 0
         };
-        this.cache.set(cacheKey, summary, 86400000);
+        this.cache.set(cacheKey, summary, 86400);
         return summary;
     }
     versionMetadataUnavailable(nodeType, extra = {}) {
@@ -2998,10 +3136,12 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
         };
     }
     async getToolsDocumentation(topic, depth = 'essentials') {
+        const disabledToolOps = this.getDisabledToolOperations();
         if (!topic || topic === 'overview') {
-            return (0, tools_documentation_1.getToolsOverview)(depth);
+            return (0, tools_documentation_1.getToolsOverview)(depth, disabledToolOps.size > 0 ? disabledToolOps : undefined);
         }
-        return (0, tools_documentation_1.getToolDocumentation)(topic, depth);
+        const toolDisabledOps = disabledToolOps.get(topic);
+        return (0, tools_documentation_1.getToolDocumentation)(topic, depth, toolDisabledOps);
     }
     async connect(transport) {
         await this.ensureInitialized();