Merge pull request #685 from czlonkowski/fix/patterns-docs-and-token-trim-683

fix: trim patterns response tokens and complete documentation (v2.42.3)

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.42.3] - 2026-03-30
+
+### Improved
+
+- **Patterns response trimmed for token efficiency** (Issue #683): Task-specific patterns response reduced ~64% — dropped redundant `displayName`, shortened field names (`frequency` → `freq`), capped chains at 5, and shortened chain node types to last segment.
+
+- **`patterns` mode added to `tools_documentation`**: Was missing from both essentials and full docs. AI agents can now discover patterns mode through the standard documentation flow.
+
+- **`includeOperations` omission behavior documented**: Added note that trigger nodes and freeform nodes (Code, HTTP Request) omit the `operationsTree` field.
+
+- **`search_nodes` examples trimmed**: Reduced from 11 to 6 examples in full docs, removing near-duplicates.
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
+## [2.42.2] - 2026-03-30
+
+### Fixed
+
+- **`workflow-patterns.json` missing from npm package** (Issue #681): Added `data/workflow-patterns.json` to the `files` array in `package.json` so the patterns file is included in the published npm package and works out of the box without manual generation.
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
 ## [2.42.1] - 2026-03-30
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.42.1",
+  "version": "2.42.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -124,6 +124,7 @@
     "dist/**/*",
     "ui-apps/dist/**/*",
     "data/nodes.db",
+    "data/workflow-patterns.json",
     ".env.example",
     "README.md",
     "LICENSE",

src/mcp/server.ts

@@ -3909,17 +3909,23 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     const patterns = this.workflowPatternsCache!;
 
     if (category) {
-      // Return specific category pattern data
+      // Return specific category pattern data (trimmed for token efficiency)
       const categoryData = patterns.categories[category];
       if (!categoryData) {
         const available = Object.keys(patterns.categories);
         return { error: `Unknown category "${category}". Available: ${available.join(', ')}` };
       }
+      const MAX_CHAINS = 5;
       return {
         category,
-        ...categoryData,
-        nodes: categoryData.nodes?.slice(0, limit),
-        commonChains: categoryData.commonChains?.slice(0, limit),
+        templateCount: categoryData.templateCount,
+        pattern: categoryData.pattern,
+        nodes: categoryData.nodes?.slice(0, limit).map(n => ({
+          type: n.type, freq: n.frequency, role: n.role
+        })),
+        chains: categoryData.commonChains?.slice(0, MAX_CHAINS).map(c => ({
+          path: c.chain.map(t => t.split('.').pop() ?? t), count: c.count, freq: c.frequency
+        })),
       };
     }
 

src/mcp/tool-docs/discovery/search-nodes.ts

@@ -26,21 +26,16 @@ export const searchNodesDoc: ToolDocumentation = {
       mode: { type: 'string', description: 'Search mode: "OR" (any word matches, default), "AND" (all words required), "FUZZY" (typo-tolerant)', required: false },
       source: { type: 'string', description: 'Filter by node source: "all" (default, everything), "core" (n8n base nodes only), "community" (community nodes only), "verified" (verified community nodes only)', required: false },
       includeExamples: { type: 'boolean', description: 'Include top 2 real-world configuration examples from popular templates for each node. Default: false. Adds ~200-400 tokens per node.', required: false },
-      includeOperations: { type: 'boolean', description: 'Include resource/operation tree per node. Default: false. Adds ~100-300 tokens per result but saves a get_node round-trip.', required: false }
+      includeOperations: { type: 'boolean', description: 'Include resource/operation tree per node. Default: false. Adds ~100-300 tokens per result but saves a get_node round-trip. Only returned for nodes with resource/operation patterns — trigger nodes and freeform nodes (Code, HTTP Request) omit this field.', required: false }
     },
     returns: 'Array of node objects sorted by relevance score. Each object contains: nodeType, displayName, description, category, relevance score. For community nodes, also includes: isCommunity (boolean), isVerified (boolean), authorName (string), npmDownloads (number). Common nodes appear first when relevance is similar.',
     examples: [
       'search_nodes({query: "webhook"}) - Returns Webhook node as top result',
-      'search_nodes({query: "database"}) - Returns MySQL, Postgres, MongoDB, Redis, etc.',
       'search_nodes({query: "google sheets", mode: "AND"}) - Requires both words',
       'search_nodes({query: "slak", mode: "FUZZY"}) - Finds Slack despite typo',
-      'search_nodes({query: "http api"}) - Finds HTTP Request, GraphQL, REST nodes',
-      'search_nodes({query: "transform data"}) - Finds Set, Code, Function, Item Lists nodes',
       'search_nodes({query: "scraping", source: "community"}) - Find community scraping nodes',
-      'search_nodes({query: "pdf", source: "verified"}) - Find verified community PDF nodes',
-      'search_nodes({query: "brightdata"}) - Find BrightData community node',
       'search_nodes({query: "slack", includeExamples: true}) - Get Slack with template examples',
-      'search_nodes({query: "slack", includeOperations: true}) - Get Slack with resource/operation tree'
+      'search_nodes({query: "slack", includeOperations: true}) - Get Slack with resource/operation tree (7 resources, 44 ops)'
     ],
     useCases: [
       'Finding nodes when you know partial names',

src/mcp/tool-docs/templates/search-templates.ts

@@ -4,7 +4,7 @@ export const searchTemplatesDoc: ToolDocumentation = {
   name: 'search_templates',
   category: 'templates',
   essentials: {
-    description: 'Unified template search with multiple modes: keyword search, by node types, by task type, or by metadata. 2,700+ templates available.',
+    description: 'Unified template search with multiple modes: keyword search, by node types, by task type, by metadata, or patterns. 2,700+ templates available.',
     keyParameters: ['searchMode', 'query', 'nodeTypes', 'task', 'limit'],
     example: 'search_templates({searchMode: "by_task", task: "webhook_processing"})',
     performance: 'Fast (<100ms) - FTS5 full-text search',
@@ -12,7 +12,9 @@ export const searchTemplatesDoc: ToolDocumentation = {
       'searchMode="keyword" (default): Search by name/description',
       'searchMode="by_nodes": Find templates using specific nodes',
       'searchMode="by_task": Get curated templates for common tasks',
-      'searchMode="by_metadata": Filter by complexity, services, audience'
+      'searchMode="by_metadata": Filter by complexity, services, audience',
+      'searchMode="patterns": Workflow pattern summaries across 10 task categories',
+      'patterns without task: overview of all categories. patterns with task: node frequencies + connection chains'
     ]
   },
   full: {
@@ -21,14 +23,15 @@ export const searchTemplatesDoc: ToolDocumentation = {
 - by_nodes: Find templates that use specific node types
 - by_task: Get curated templates for predefined task categories
 - by_metadata: Filter by complexity, setup time, required services, or target audience
+- patterns: Lightweight workflow pattern summaries mined from 2,700+ templates
 
-**Available Task Types (for searchMode="by_task"):**
+**Available Task Types (for searchMode="by_task" and "patterns"):**
 ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations`,
     parameters: {
       searchMode: {
         type: 'string',
         required: false,
-        description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata"'
+        description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata", "patterns"'
       },
       query: {
         type: 'string',
@@ -43,7 +46,7 @@ ai_automation, data_sync, webhook_processing, email_automation, slack_integratio
       task: {
         type: 'string',
         required: false,
-        description: 'For searchMode=by_task: Task type (ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations)'
+        description: 'For searchMode=by_task: Task type. For searchMode=patterns: optional category filter (omit for overview of all categories). Values: ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations'
       },
       complexity: {
         type: 'string',
@@ -91,38 +94,45 @@ ai_automation, data_sync, webhook_processing, email_automation, slack_integratio
         description: 'Pagination offset (default 0)'
       }
     },
-    returns: `Returns an object containing:
+    returns: `For keyword/by_nodes/by_task/by_metadata modes:
 - templates: Array of matching templates
   - id: Template ID for get_template()
-  - name: Template name
-  - description: What the workflow does
-  - author: Creator information
-  - nodes: Array of node types used
-  - views: Popularity metric
-  - created: Creation date
-  - url: Link to template
-  - metadata: AI-generated metadata (complexity, services, etc.)
+  - name, description, author, nodes, views, created, url, metadata
 - totalFound: Total matching templates
-- searchMode: The mode used`,
+- searchMode: The mode used
+
+For patterns mode (no task):
+- templateCount, generatedAt
+- categories: Array of {category, templateCount, pattern, topNodes}
+- tip: How to drill into a specific category
+
+For patterns mode (with task):
+- category, templateCount, pattern
+- nodes: Array of {type, freq, role} (top nodes by frequency, limited by 'limit')
+- chains: Array of {path, count, freq} (top 5 connection chains, short node names)`,
     examples: [
       '// Keyword search (default)\nsearch_templates({query: "chatbot"})',
       '// Find templates using specific nodes\nsearch_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})',
       '// Get templates for a task type\nsearch_templates({searchMode: "by_task", task: "webhook_processing"})',
       '// Filter by metadata\nsearch_templates({searchMode: "by_metadata", complexity: "simple", requiredService: "openai"})',
-      '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})'
+      '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})',
+      '// Pattern overview — all categories with top nodes (~550 tokens)\nsearch_templates({searchMode: "patterns"})',
+      '// Detailed patterns for a category — node frequencies + connection chains\nsearch_templates({searchMode: "patterns", task: "ai_automation"})'
     ],
     useCases: [
       'Find workflows by business purpose (keyword search)',
       'Find templates using specific integrations (by_nodes)',
       'Get pre-built solutions for common tasks (by_task)',
       'Filter by complexity for team skill level (by_metadata)',
-      'Find templates requiring specific services (by_metadata)'
+      'Understand common workflow shapes before building (patterns)',
+      'Architecture planning — which nodes go together (patterns)'
     ],
     performance: `Fast performance across all modes:
 - keyword: <50ms with FTS5 indexing
 - by_nodes: <100ms with indexed lookups
 - by_task: <50ms from curated cache
-- by_metadata: <100ms with filtered queries`,
+- by_metadata: <100ms with filtered queries
+- patterns: <10ms (pre-mined, cached in memory)`,
     bestPractices: [
       'Use searchMode="by_task" for common automation patterns',
       'Use searchMode="by_nodes" when you know which integrations you need',

src/mcp/tools-documentation.ts

@@ -125,6 +125,7 @@ When working with Code nodes, always start by calling the relevant guide:
   - searchMode='by_nodes': Find templates using specific nodes
   - searchMode='by_task': Curated task-based templates
   - searchMode='by_metadata': Filter by complexity/services
+  - searchMode='patterns': Workflow pattern summaries from 2,700+ templates
 
 **n8n API Tools** (13 tools, requires N8N_API_URL configuration)
 - n8n_create_workflow - Create new workflows