n8n-mcp 2.10.9 → 2.11.1

package/.env.example

@@ -86,4 +86,24 @@ AUTH_TOKEN=your-secure-token-here
 # N8N_API_TIMEOUT=30000
 
 # Maximum number of API request retries (default: 3)
-# N8N_API_MAX_RETRIES=3
+# N8N_API_MAX_RETRIES=3
+
+# =========================
+# OPENAI API CONFIGURATION
+# =========================
+# Optional: Enable AI-powered template metadata generation
+# Provides structured metadata for improved template discovery
+
+# OpenAI API Key (get from https://platform.openai.com/api-keys)
+# OPENAI_API_KEY=
+
+# OpenAI Model for metadata generation (default: gpt-4o-mini)
+# OPENAI_MODEL=gpt-4o-mini
+
+# Batch size for metadata generation (default: 100)
+# Templates are processed in batches using OpenAI's Batch API for 50% cost savings
+# OPENAI_BATCH_SIZE=100
+
+# Enable metadata generation during template fetch (default: false)
+# Set to true to automatically generate metadata when running fetch:templates
+# METADATA_GENERATION_ENABLED=false

package/README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-mcp?style=social)](https://github.com/czlonkowski/n8n-mcp)
-[![Version](https://img.shields.io/badge/version-2.10.9-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
+[![Version](https://img.shields.io/badge/version-2.11.1-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
 [![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
 [![Tests](https://img.shields.io/badge/tests-1728%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
@@ -357,38 +357,55 @@ You are an expert in n8n automation software using n8n-MCP tools. Your role is t
 
 1. **ALWAYS start new conversation with**: `tools_documentation()` to understand best practices and available tools.
 
-2. **Discovery Phase** - Find the right nodes:
+2. **Template Discovery Phase** 
+   - `search_templates_by_metadata({complexity: "simple"})` - Find skill-appropriate templates
+   - `get_templates_for_task('webhook_processing')` - Get curated templates by task
+   - `search_templates('slack notification')` - Text search for specific needs
+   - `list_node_templates(['n8n-nodes-base.slack'])` - Find templates using specific nodes
+   
+   **Template filtering strategies**:
+   - **For beginners**: `complexity: "simple"` and `maxSetupMinutes: 30`
+   - **By role**: `targetAudience: "marketers"` or `"developers"` or `"analysts"`
+   - **By time**: `maxSetupMinutes: 15` for quick wins
+   - **By service**: `requiredService: "openai"` to find compatible templates
+
+3. **Discovery Phase** - Find the right nodes (if no suitable template):
    - Think deeply about user request and the logic you are going to build to fulfill it. Ask follow-up questions to clarify the user's intent, if something is unclear. Then, proceed with the rest of your instructions.
    - `search_nodes({query: 'keyword'})` - Search by functionality
    - `list_nodes({category: 'trigger'})` - Browse by category
    - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!)
 
-3. **Configuration Phase** - Get node details efficiently:
+4. **Configuration Phase** - Get node details efficiently:
    - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties
    - `search_node_properties(nodeType, 'auth')` - Find specific properties
    - `get_node_for_task('send_email')` - Get pre-configured templates
    - `get_node_documentation(nodeType)` - Human-readable docs when needed
    - It is good common practice to show a visual representation of the workflow architecture to the user and asking for opinion, before moving forward. 
 
-4. **Pre-Validation Phase** - Validate BEFORE building:
+5. **Pre-Validation Phase** - Validate BEFORE building:
    - `validate_node_minimal(nodeType, config)` - Quick required fields check
    - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation
    - Fix any validation errors before proceeding
 
-5. **Building Phase** - Create the workflow:
-   - Use validated configurations from step 4
+6. **Building Phase** - Create or customize the workflow:
+   - If using template: `get_template(templateId, {mode: "full"})`
+   - **MANDATORY ATTRIBUTION**: When using a template, ALWAYS inform the user:
+     - "This workflow is based on a template by **[author.name]** (@[author.username])"
+     - "View the original template at: [url]"
+     - Example: "This workflow is based on a template by **David Ashby** (@cfomodz). View the original at: https://n8n.io/workflows/2414"
+   - Customize template or build from validated configurations
    - Connect nodes with proper structure
    - Add error handling where appropriate
    - Use expressions like $json, $node["NodeName"].json
    - Build the workflow in an artifact for easy editing downstream (unless the user asked to create in n8n instance)
 
-6. **Workflow Validation Phase** - Validate complete workflow:
+7. **Workflow Validation Phase** - Validate complete workflow:
    - `validate_workflow(workflow)` - Complete validation including connections
    - `validate_workflow_connections(workflow)` - Check structure and AI tool connections
    - `validate_workflow_expressions(workflow)` - Validate all n8n expressions
    - Fix any issues found before deployment
 
-7. **Deployment Phase** (if n8n API configured):
+8. **Deployment Phase** (if n8n API configured):
    - `n8n_create_workflow(workflow)` - Deploy validated workflow
    - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation
    - `n8n_update_partial_workflow()` - Make incremental updates using diffs
@@ -396,6 +413,9 @@ You are an expert in n8n automation software using n8n-MCP tools. Your role is t
 
 ## Key Insights
 
+- **TEMPLATES FIRST** - Always check for existing templates before building from scratch (2,500+ available!)
+- **ATTRIBUTION REQUIRED** - Always credit template authors with name, username, and link to n8n.io
+- **SMART FILTERING** - Use metadata filters to find templates matching user skill level and time constraints
 - **USE CODE NODE ONLY WHEN IT IS NECESSARY** - always prefer to use standard nodes over code node. Use code node only when you are sure you need it.
 - **VALIDATE EARLY AND OFTEN** - Catch errors before they reach deployment
 - **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings
@@ -434,27 +454,50 @@ You are an expert in n8n automation software using n8n-MCP tools. Your role is t
 
 ## Example Workflow
 
-### 1. Discovery & Configuration
+### Smart Template-First Approach
+
+#### 1. Find existing templates
+// Find simple Slack templates for marketers
+const templates = search_templates_by_metadata({
+  requiredService: 'slack',
+  complexity: 'simple',
+  targetAudience: 'marketers',
+  maxSetupMinutes: 30
+})
+
+// Or search by text
+search_templates('slack notification')
+
+// Or get curated templates
+get_templates_for_task('slack_integration')
+
+#### 2. Use and customize template
+const workflow = get_template(templates.items[0].id, {mode: 'full'})
+validate_workflow(workflow)
+
+### Building from Scratch (if no suitable template)
+
+#### 1. Discovery & Configuration
 search_nodes({query: 'slack'})
 get_node_essentials('n8n-nodes-base.slack')
 
-### 2. Pre-Validation
+#### 2. Pre-Validation
 validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'})
 validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime')
 
-### 3. Build Workflow
+#### 3. Build Workflow
 // Create workflow JSON with validated configs
 
-### 4. Workflow Validation
+#### 4. Workflow Validation
 validate_workflow(workflowJson)
 validate_workflow_connections(workflowJson)
 validate_workflow_expressions(workflowJson)
 
-### 5. Deploy (if configured)
+#### 5. Deploy (if configured)
 n8n_create_workflow(validatedWorkflow)
 n8n_validate_workflow({id: createdWorkflowId})
 
-### 6. Update Using Diffs
+#### 6. Update Using Diffs
 n8n_update_partial_workflow({
   workflowId: id,
   operations: [
@@ -464,15 +507,24 @@ n8n_update_partial_workflow({
 
 ## Important Rules
 
-- ALWAYS validate before building
-- ALWAYS validate after building
-- NEVER deploy unvalidated workflows
+- ALWAYS check for existing templates before building from scratch
+- LEVERAGE metadata filters to find skill-appropriate templates
+- **ALWAYS ATTRIBUTE TEMPLATES**: When using any template, you MUST share the author's name, username, and link to the original template on n8n.io
+- VALIDATE templates before deployment (they may need updates)
 - USE diff operations for updates (80-90% token savings)
 - STATE validation results clearly
 - FIX all errors before proceeding
+
+## Template Discovery Tips
+
+- **97.5% of templates have metadata** - Use smart filtering!
+- **Filter combinations work best** - Combine complexity + setup time + service
+- **Templates save 70-90% development time** - Always check first
+- **Metadata is AI-generated** - Occasionally imprecise but highly useful
+- **Use `includeMetadata: false` for fast browsing** - Add metadata only when needed
 ```
 
-Save these instructions in your Claude Project for optimal n8n workflow assistance with comprehensive validation.
+Save these instructions in your Claude Project for optimal n8n workflow assistance with intelligent template discovery.
 
 ## 🚨 Important: Sharing Guidelines
 
@@ -524,6 +576,14 @@ Once connected, Claude can use these powerful tools:
 - **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
 - **`get_node_as_tool_info`** - Get guidance on using any node as an AI tool
 
+### Template Tools
+- **`list_templates`** - Browse all templates with descriptions and optional metadata (2,500+ templates)
+- **`search_templates`** - Text search across template names and descriptions
+- **`search_templates_by_metadata`** - Advanced filtering by complexity, setup time, services, audience
+- **`list_node_templates`** - Find templates using specific nodes
+- **`get_template`** - Get complete workflow JSON for import
+- **`get_templates_for_task`** - Curated templates for common automation tasks
+
 ### Advanced Tools
 - **`get_node_for_task`** - Pre-configured node settings for common tasks
 - **`list_tasks`** - Discover available task templates
@@ -807,6 +867,23 @@ See [Automated Release Guide](./docs/AUTOMATED_RELEASES.md) for complete details
 - [Anthropic](https://anthropic.com) for the Model Context Protocol
 - All contributors and users of this project
 
+### Template Attribution
+
+All workflow templates in this project are fetched from n8n's public template gallery at [n8n.io/workflows](https://n8n.io/workflows). Each template includes:
+- Full attribution to the original creator (name and username)
+- Direct link to the source template on n8n.io
+- Original workflow ID for reference
+
+The AI agent instructions in this project contain mandatory attribution requirements. When using any template, the AI will automatically:
+- Share the template author's name and username
+- Provide a direct link to the original template on n8n.io
+- Display attribution in the format: "This workflow is based on a template by **[author]** (@[username]). View the original at: [url]"
+
+Template creators retain all rights to their workflows. This project indexes templates to improve discoverability through AI assistants. If you're a template creator and have concerns about your template being indexed, please open an issue.
+
+Special thanks to the prolific template contributors whose work helps thousands of users automate their workflows, including:
+**David Ashby** (@cfomodz), **Yaron Been** (@yaron-nofluff), **Jimleuk** (@jimleuk), **Davide** (@n3witalia), **David Olusola** (@dae221), **Ranjan Dailata** (@ranjancse), **Airtop** (@cesar-at-airtop), **Joseph LePage** (@joe), **Don Jayamaha Jr** (@don-the-gem-dealer), **Angel Menendez** (@djangelic), and the entire n8n community of creators!
+
 ---
 
 <div align="center">

package/dist/mcp/server.d.ts

@@ -43,10 +43,12 @@ export declare class N8NDocumentationMCPServer {
     private validateNodeMinimal;
     private getToolsDocumentation;
     connect(transport: any): Promise<void>;
+    private listTemplates;
     private listNodeTemplates;
     private getTemplate;
     private searchTemplates;
     private getTemplatesForTask;
+    private searchTemplatesByMetadata;
     private getTaskDescription;
     private validateWorkflow;
     private validateWorkflowConnections;

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAuDA,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,EAAE,CAAgC;IAC1C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,UAAU,CAAa;;YA4DjB,kBAAkB;YAkBlB,wBAAwB;YAgBxB,iBAAiB;IAO/B,OAAO,CAAC,aAAa;IA0NrB,OAAO,CAAC,wBAAwB;IAoFhC,OAAO,CAAC,kBAAkB;IAoE1B,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,qBAAqB;YAsQf,SAAS;YA2DT,WAAW;YAiEX,WAAW;YAsCX,cAAc;YAiId,gBAAgB;IAqD9B,OAAO,CAAC,mBAAmB;IAwE3B,OAAO,CAAC,eAAe;YAsBT,eAAe;IAqE7B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,uBAAuB;IA0D/B,OAAO,CAAC,iBAAiB;YAqFX,WAAW;YAgCX,oBAAoB;YAyEpB,qBAAqB;YAuCrB,iBAAiB;YA+EjB,oBAAoB;YAsDpB,cAAc;IAqC5B,OAAO,CAAC,gBAAgB;YAiBV,SAAS;YA6CT,kBAAkB;YA+DlB,uBAAuB;YAsDvB,iBAAiB;IAqE/B,OAAO,CAAC,qBAAqB;IA8C7B,OAAO,CAAC,uBAAuB;IAwD/B,OAAO,CAAC,iBAAiB;YAoDX,mBAAmB;YAkGnB,qBAAqB;IAS7B,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAS9B,iBAAiB;YAqBjB,WAAW;YAmBX,eAAe;YAqBf,mBAAmB;IAuBjC,OAAO,CAAC,kBAAkB;YAiBZ,gBAAgB;YA6GhB,2BAA2B;YAiE3B,2BAA2B;IAyEnC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BpB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAuBhC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAuDA,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,EAAE,CAAgC;IAC1C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,UAAU,CAAa;;YA4DjB,kBAAkB;YAkBlB,wBAAwB;YAgBxB,iBAAiB;IAO/B,OAAO,CAAC,aAAa;IA0NrB,OAAO,CAAC,wBAAwB;IAoFhC,OAAO,CAAC,kBAAkB;IAoE1B,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,qBAAqB;YA+Rf,SAAS;YA2DT,WAAW;YAiEX,WAAW;YAsCX,cAAc;YAiId,gBAAgB;IAqD9B,OAAO,CAAC,mBAAmB;IAwE3B,OAAO,CAAC,eAAe;YAsBT,eAAe;IAqE7B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,uBAAuB;IA0D/B,OAAO,CAAC,iBAAiB;YAqFX,WAAW;YAgCX,oBAAoB;YAyEpB,qBAAqB;YAwDrB,iBAAiB;YA+EjB,oBAAoB;YAsDpB,cAAc;IAqC5B,OAAO,CAAC,gBAAgB;YAiBV,SAAS;YA6CT,kBAAkB;YA+DlB,uBAAuB;YAsDvB,iBAAiB;IAqE/B,OAAO,CAAC,qBAAqB;IA8C7B,OAAO,CAAC,uBAAuB;IAwD/B,OAAO,CAAC,iBAAiB;YAoDX,mBAAmB;YAkGnB,qBAAqB;IAS7B,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAS9B,aAAa;YAcb,iBAAiB;YAoBjB,WAAW;YAwBX,eAAe;YAqBf,mBAAmB;YAwBnB,yBAAyB;IA4CvC,OAAO,CAAC,kBAAkB;YAiBZ,gBAAgB;YA6GhB,2BAA2B;YAiE3B,2BAA2B;IAyEnC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BpB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAuBhC"}

package/dist/mcp/server.js

@@ -592,21 +592,44 @@ class N8NDocumentationMCPServer {
             case 'get_node_as_tool_info':
                 this.validateToolParams(name, args, ['nodeType']);
                 return this.getNodeAsToolInfo(args.nodeType);
+            case 'list_templates':
+                const listLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
+                const listOffset = Math.max(Number(args.offset) || 0, 0);
+                const sortBy = args.sortBy || 'views';
+                const includeMetadata = Boolean(args.includeMetadata);
+                return this.listTemplates(listLimit, listOffset, sortBy, includeMetadata);
             case 'list_node_templates':
                 this.validateToolParams(name, args, ['nodeTypes']);
-                const templateLimit = args.limit !== undefined ? Number(args.limit) || 10 : 10;
-                return this.listNodeTemplates(args.nodeTypes, templateLimit);
+                const templateLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
+                const templateOffset = Math.max(Number(args.offset) || 0, 0);
+                return this.listNodeTemplates(args.nodeTypes, templateLimit, templateOffset);
             case 'get_template':
                 this.validateToolParams(name, args, ['templateId']);
                 const templateId = Number(args.templateId);
-                return this.getTemplate(templateId);
+                const mode = args.mode || 'full';
+                return this.getTemplate(templateId, mode);
             case 'search_templates':
                 this.validateToolParams(name, args, ['query']);
-                const searchLimit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
-                return this.searchTemplates(args.query, searchLimit);
+                const searchLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
+                const searchOffset = Math.max(Number(args.offset) || 0, 0);
+                const searchFields = args.fields;
+                return this.searchTemplates(args.query, searchLimit, searchOffset, searchFields);
             case 'get_templates_for_task':
                 this.validateToolParams(name, args, ['task']);
-                return this.getTemplatesForTask(args.task);
+                const taskLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
+                const taskOffset = Math.max(Number(args.offset) || 0, 0);
+                return this.getTemplatesForTask(args.task, taskLimit, taskOffset);
+            case 'search_templates_by_metadata':
+                const metadataLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
+                const metadataOffset = Math.max(Number(args.offset) || 0, 0);
+                return this.searchTemplatesByMetadata({
+                    category: args.category,
+                    complexity: args.complexity,
+                    maxSetupMinutes: args.maxSetupMinutes ? Number(args.maxSetupMinutes) : undefined,
+                    minSetupMinutes: args.minSetupMinutes ? Number(args.minSetupMinutes) : undefined,
+                    requiredService: args.requiredService,
+                    targetAudience: args.targetAudience
+                }, metadataLimit, metadataOffset);
             case 'validate_workflow':
                 this.validateToolParams(name, args, ['workflow']);
                 return this.validateWorkflow(args.workflow, args.options);
@@ -1262,8 +1285,17 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
       FROM nodes 
       GROUP BY package_name
     `).all();
+        const templateStats = this.db.prepare(`
+      SELECT 
+        COUNT(*) as total_templates,
+        AVG(views) as avg_views,
+        MIN(views) as min_views,
+        MAX(views) as max_views
+      FROM templates
+    `).get();
         return {
             totalNodes: stats.total,
+            totalTemplates: templateStats.total_templates || 0,
             statistics: {
                 aiTools: stats.ai_tools,
                 triggers: stats.triggers,
@@ -1272,6 +1304,12 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
                 documentationCoverage: Math.round((stats.with_docs / stats.total) * 100) + '%',
                 uniquePackages: stats.packages,
                 uniqueCategories: stats.categories,
+                templates: {
+                    total: templateStats.total_templates || 0,
+                    avgViews: Math.round(templateStats.avg_views || 0),
+                    minViews: templateStats.min_views || 0,
+                    maxViews: templateStats.max_views || 0
+                }
             },
             packageBreakdown: packages.map(pkg => ({
                 package: pkg.package_name,
@@ -1810,76 +1848,128 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
             transportType: transport.constructor.name
         });
     }
-    async listNodeTemplates(nodeTypes, limit = 10) {
+    async listTemplates(limit = 10, offset = 0, sortBy = 'views', includeMetadata = false) {
+        await this.ensureInitialized();
+        if (!this.templateService)
+            throw new Error('Template service not initialized');
+        const result = await this.templateService.listTemplates(limit, offset, sortBy, includeMetadata);
+        return {
+            ...result,
+            tip: result.items.length > 0 ?
+                `Use get_template(templateId) to get full workflow details. Total: ${result.total} templates available.` :
+                "No templates found. Run 'npm run fetch:templates' to update template database"
+        };
+    }
+    async listNodeTemplates(nodeTypes, limit = 10, offset = 0) {
         await this.ensureInitialized();
         if (!this.templateService)
             throw new Error('Template service not initialized');
-        const templates = await this.templateService.listNodeTemplates(nodeTypes, limit);
-        if (templates.length === 0) {
+        const result = await this.templateService.listNodeTemplates(nodeTypes, limit, offset);
+        if (result.items.length === 0 && offset === 0) {
             return {
+                ...result,
                 message: `No templates found using nodes: ${nodeTypes.join(', ')}`,
-                tip: "Try searching with more common nodes or run 'npm run fetch:templates' to update template database",
-                templates: []
+                tip: "Try searching with more common nodes or run 'npm run fetch:templates' to update template database"
             };
         }
         return {
-            templates,
-            count: templates.length,
-            tip: `Use get_template(templateId) to get the full workflow JSON for any template`
+            ...result,
+            tip: `Showing ${result.items.length} of ${result.total} templates. Use offset for pagination.`
         };
     }
-    async getTemplate(templateId) {
+    async getTemplate(templateId, mode = 'full') {
         await this.ensureInitialized();
         if (!this.templateService)
             throw new Error('Template service not initialized');
-        const template = await this.templateService.getTemplate(templateId);
+        const template = await this.templateService.getTemplate(templateId, mode);
         if (!template) {
             return {
                 error: `Template ${templateId} not found`,
-                tip: "Use list_node_templates or search_templates to find available templates"
+                tip: "Use list_templates, list_node_templates or search_templates to find available templates"
             };
         }
+        const usage = mode === 'nodes_only' ? "Node list for quick overview" :
+            mode === 'structure' ? "Workflow structure without full details" :
+                "Complete workflow JSON ready to import into n8n";
         return {
+            mode,
             template,
-            usage: "Import this workflow JSON directly into n8n or use it as a reference for building workflows"
+            usage
         };
     }
-    async searchTemplates(query, limit = 20) {
+    async searchTemplates(query, limit = 20, offset = 0, fields) {
         await this.ensureInitialized();
         if (!this.templateService)
             throw new Error('Template service not initialized');
-        const templates = await this.templateService.searchTemplates(query, limit);
-        if (templates.length === 0) {
+        const result = await this.templateService.searchTemplates(query, limit, offset, fields);
+        if (result.items.length === 0 && offset === 0) {
             return {
+                ...result,
                 message: `No templates found matching: "${query}"`,
-                tip: "Try different keywords or run 'npm run fetch:templates' to update template database",
-                templates: []
+                tip: "Try different keywords or run 'npm run fetch:templates' to update template database"
             };
         }
         return {
-            templates,
-            count: templates.length,
-            query
+            ...result,
+            query,
+            tip: `Found ${result.total} templates matching "${query}". Showing ${result.items.length}.`
         };
     }
-    async getTemplatesForTask(task) {
+    async getTemplatesForTask(task, limit = 10, offset = 0) {
         await this.ensureInitialized();
         if (!this.templateService)
             throw new Error('Template service not initialized');
-        const templates = await this.templateService.getTemplatesForTask(task);
+        const result = await this.templateService.getTemplatesForTask(task, limit, offset);
         const availableTasks = this.templateService.listAvailableTasks();
-        if (templates.length === 0) {
+        if (result.items.length === 0 && offset === 0) {
             return {
+                ...result,
                 message: `No templates found for task: ${task}`,
                 availableTasks,
                 tip: "Try a different task or use search_templates for custom searches"
             };
         }
         return {
+            ...result,
             task,
-            templates,
-            count: templates.length,
-            description: this.getTaskDescription(task)
+            description: this.getTaskDescription(task),
+            tip: `${result.total} templates available for ${task}. Showing ${result.items.length}.`
+        };
+    }
+    async searchTemplatesByMetadata(filters, limit = 20, offset = 0) {
+        await this.ensureInitialized();
+        if (!this.templateService)
+            throw new Error('Template service not initialized');
+        const result = await this.templateService.searchTemplatesByMetadata(filters, limit, offset);
+        const filterSummary = [];
+        if (filters.category)
+            filterSummary.push(`category: ${filters.category}`);
+        if (filters.complexity)
+            filterSummary.push(`complexity: ${filters.complexity}`);
+        if (filters.maxSetupMinutes)
+            filterSummary.push(`max setup: ${filters.maxSetupMinutes} min`);
+        if (filters.minSetupMinutes)
+            filterSummary.push(`min setup: ${filters.minSetupMinutes} min`);
+        if (filters.requiredService)
+            filterSummary.push(`service: ${filters.requiredService}`);
+        if (filters.targetAudience)
+            filterSummary.push(`audience: ${filters.targetAudience}`);
+        if (result.items.length === 0 && offset === 0) {
+            const availableCategories = await this.templateService.getAvailableCategories();
+            const availableAudiences = await this.templateService.getAvailableTargetAudiences();
+            return {
+                ...result,
+                message: `No templates found with filters: ${filterSummary.join(', ')}`,
+                availableCategories: availableCategories.slice(0, 10),
+                availableAudiences: availableAudiences.slice(0, 5),
+                tip: "Try broader filters or different categories. Use list_templates to see all templates."
+            };
+        }
+        return {
+            ...result,
+            filters,
+            filterSummary: filterSummary.join(', '),
+            tip: `Found ${result.total} templates matching filters. Showing ${result.items.length}. Each includes AI-generated metadata.`
         };
     }
     getTaskDescription(task) {