ros/n8n-mcp
1
0
Fork 0
mirror of https://github.com/czlonkowski/n8n-mcp.git synced 2026-02-09 14:53:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add template metadata generation and smart discovery

Browse Source 
- Implement OpenAI batch API integration for metadata generation
- Add search_templates_by_metadata tool with advanced filtering
- Enhance list_templates to include descriptions and optional metadata
- Generate metadata for 2,534 templates (97.5% coverage)
- Update README with Template Tools section and enhanced Claude setup
- Add comprehensive documentation for metadata system

Enables intelligent template discovery through:
- Complexity levels (simple/medium/complex)
- Setup time estimates (5-480 minutes)
- Target audience filtering (developers/marketers/analysts)
- Required services detection
- Category and use case classification

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-09-15 00:18:53 +02:00
parent 6e24da722b
commit 1e586c0b23
15 changed files with 1159 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
src/mcp/server.ts
View File

@@ -730,7 +730,8 @@ export class N8NDocumentationMCPServer {
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';
return this.listTemplates(listLimit, listOffset, sortBy);
const includeMetadata = Boolean(args.includeMetadata);
return this.listTemplates(listLimit, listOffset, sortBy, includeMetadata);
case 'list_node_templates':
this.validateToolParams(name, args, ['nodeTypes']);
const templateLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
@@ -751,6 +752,18 @@ export class N8NDocumentationMCPServer {
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':
// No required params - all filters are optional
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);
@@ -2328,11 +2341,11 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
}
// Template-related methods
private async listTemplates(limit: number = 10, offset: number = 0, sortBy: 'views' | 'created_at' | 'name' = 'views'): Promise<any> {
private async listTemplates(limit: number = 10, offset: number = 0, sortBy: 'views' | 'created_at' | 'name' = 'views', includeMetadata: boolean = false): Promise<any> {
await this.ensureInitialized();
if (!this.templateService) throw new Error('Template service not initialized');
const result = await this.templateService.listTemplates(limit, offset, sortBy);
const result = await this.templateService.listTemplates(limit, offset, sortBy, includeMetadata);
return {
...result,
@@ -2431,6 +2444,50 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
};
}
private async searchTemplatesByMetadata(filters: {
category?: string;
complexity?: 'simple' | 'medium' | 'complex';
maxSetupMinutes?: number;
minSetupMinutes?: number;
requiredService?: string;
targetAudience?: string;
}, limit: number = 20, offset: number = 0): Promise<any> {
await this.ensureInitialized();
if (!this.templateService) throw new Error('Template service not initialized');
const result = await this.templateService.searchTemplatesByMetadata(filters, limit, offset);
// Build filter summary for feedback
const filterSummary: string[] = [];
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) {
// Get available categories and audiences for suggestions
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.`
};
}
private getTaskDescription(task: string): string {
const descriptions: Record<string, string> = {
'ai_automation': 'AI-powered workflows using OpenAI, LangChain, and other AI tools',

4
src/mcp/tool-docs/index.ts
View File

@@ -22,7 +22,8 @@ import {
getNodeForTaskDoc,
listNodeTemplatesDoc,
getTemplateDoc,
searchTemplatesDoc,
searchTemplatesDoc,
searchTemplatesByMetadataDoc,
getTemplatesForTaskDoc
} from './templates';
import {
@@ -83,6 +84,7 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
list_node_templates: listNodeTemplatesDoc,
get_template: getTemplateDoc,
search_templates: searchTemplatesDoc,
search_templates_by_metadata: searchTemplatesByMetadataDoc,
get_templates_for_task: getTemplatesForTaskDoc,
// Workflow Management tools (n8n API)

1
src/mcp/tool-docs/templates/index.ts
View File

@@ -3,4 +3,5 @@ export { listTasksDoc } from './list-tasks';
export { listNodeTemplatesDoc } from './list-node-templates';
export { getTemplateDoc } from './get-template';
export { searchTemplatesDoc } from './search-templates';
export { searchTemplatesByMetadataDoc } from './search-templates-by-metadata';
export { getTemplatesForTaskDoc } from './get-templates-for-task';

118
src/mcp/tool-docs/templates/search-templates-by-metadata.ts Normal file
View File

@@ -0,0 +1,118 @@
import { ToolDocumentation } from '../types';
export const searchTemplatesByMetadataDoc: ToolDocumentation = {
name: 'search_templates_by_metadata',
category: 'templates',
essentials: {
description: 'Search templates using AI-generated metadata filters. Find templates by complexity, setup time, required services, or target audience. Enables smart template discovery beyond simple text search.',
keyParameters: ['category', 'complexity', 'maxSetupMinutes', 'targetAudience'],
example: 'search_templates_by_metadata({complexity: "simple", maxSetupMinutes: 30})',
performance: 'Fast (<100ms) - JSON extraction queries',
tips: [
'All filters are optional - combine them for precise results',
'Use getAvailableCategories() to see valid category values',
'Complexity levels: simple, medium, complex',
'Setup time is in minutes (5-480 range)'
]
},
full: {
description: `Advanced template search using AI-generated metadata. Each template has been analyzed by GPT-4 to extract structured information about its purpose, complexity, setup requirements, and target users. This enables intelligent filtering beyond simple keyword matching, helping you find templates that match your specific needs, skill level, and available time.`,
parameters: {
category: {
type: 'string',
required: false,
description: 'Filter by category like "automation", "integration", "data processing", "communication". Use template service getAvailableCategories() for full list.'
},
complexity: {
type: 'string (enum)',
required: false,
description: 'Filter by implementation complexity: "simple" (beginner-friendly), "medium" (some experience needed), or "complex" (advanced features)'
},
maxSetupMinutes: {
type: 'number',
required: false,
description: 'Maximum acceptable setup time in minutes (5-480). Find templates you can implement within your time budget.'
},
minSetupMinutes: {
type: 'number',
required: false,
description: 'Minimum setup time in minutes (5-480). Find more substantial templates that offer comprehensive solutions.'
},
requiredService: {
type: 'string',
required: false,
description: 'Filter by required external service like "openai", "slack", "google", "shopify". Ensures you have necessary accounts/APIs.'
},
targetAudience: {
type: 'string',
required: false,
description: 'Filter by intended users: "developers", "marketers", "analysts", "operations", "sales". Find templates for your role.'
},
limit: {
type: 'number',
required: false,
description: 'Maximum results to return. Default 20, max 100.'
},
offset: {
type: 'number',
required: false,
description: 'Pagination offset for results. Default 0.'
}
},
returns: `Returns an object containing:
- items: Array of matching templates with full metadata
- id: Template ID
- name: Template name
- description: Purpose and functionality
- author: Creator details
- nodes: Array of nodes used
- views: Popularity count
- metadata: AI-generated structured data
- categories: Primary use categories
- complexity: Difficulty level
- use_cases: Specific applications
- estimated_setup_minutes: Time to implement
- required_services: External dependencies
- key_features: Main capabilities
- target_audience: Intended users
- total: Total matching templates
- filters: Applied filter criteria
- filterSummary: Human-readable filter description
- availableCategories: Suggested categories if no results
- availableAudiences: Suggested audiences if no results
- tip: Contextual guidance`,
examples: [
'search_templates_by_metadata({complexity: "simple"}) - Find beginner-friendly templates',
'search_templates_by_metadata({category: "automation", maxSetupMinutes: 30}) - Quick automation templates',
'search_templates_by_metadata({targetAudience: "marketers"}) - Marketing-focused workflows',
'search_templates_by_metadata({requiredService: "openai", complexity: "medium"}) - AI templates with moderate complexity',
'search_templates_by_metadata({minSetupMinutes: 60, category: "integration"}) - Comprehensive integration solutions'
],
useCases: [
'Finding beginner-friendly templates by setting complexity:"simple"',
'Discovering templates you can implement quickly with maxSetupMinutes:30',
'Finding role-specific workflows with targetAudience filter',
'Identifying templates that need specific APIs with requiredService filter',
'Combining multiple filters for precise template discovery'
],
performance: 'Fast (<100ms) - Uses SQLite JSON extraction on pre-generated metadata. 97.5% coverage (2,534/2,598 templates).',
bestPractices: [
'Start with broad filters and narrow down based on results',
'Use getAvailableCategories() to discover valid category values',
'Combine complexity and setup time for skill-appropriate templates',
'Check required services before selecting templates to ensure you have necessary accounts'
],
pitfalls: [
'Not all templates have metadata (97.5% coverage)',
'Setup time estimates assume basic n8n familiarity',
'Categories/audiences use partial matching - be specific',
'Metadata is AI-generated and may occasionally be imprecise'
],
relatedTools: [
'list_templates',
'search_templates',
'list_node_templates',
'get_templates_for_task'
]
}
};

58
src/mcp/tools.ts
View File

@@ -325,7 +325,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'list_templates',
description: `List all templates with minimal data (id, name, views, node count). Use for browsing available templates.`,
description: `List all templates with minimal data (id, name, description, views, node count). Optionally include AI-generated metadata for smart filtering.`,
inputSchema: {
type: 'object',
properties: {
@@ -348,6 +348,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
description: 'Sort field. Default: views (popularity).',
default: 'views',
},
includeMetadata: {
type: 'boolean',
description: 'Include AI-generated metadata (categories, complexity, setup time, etc.). Default false.',
default: false,
},
},
},
},
@@ -465,6 +470,57 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
required: ['task'],
},
},
{
name: 'search_templates_by_metadata',
description: `Search templates by AI-generated metadata. Filter by category, complexity, setup time, services, or audience. Returns rich metadata for smart template discovery.`,
inputSchema: {
type: 'object',
properties: {
category: {
type: 'string',
description: 'Filter by category (e.g., "automation", "integration", "data processing")',
},
complexity: {
type: 'string',
enum: ['simple', 'medium', 'complex'],
description: 'Filter by complexity level',
},
maxSetupMinutes: {
type: 'number',
description: 'Maximum setup time in minutes',
minimum: 5,
maximum: 480,
},
minSetupMinutes: {
type: 'number',
description: 'Minimum setup time in minutes',
minimum: 5,
maximum: 480,
},
requiredService: {
type: 'string',
description: 'Filter by required service (e.g., "openai", "slack", "google")',
},
targetAudience: {
type: 'string',
description: 'Filter by target audience (e.g., "developers", "marketers", "analysts")',
},
limit: {
type: 'number',
description: 'Maximum number of results. Default 20.',
default: 20,
minimum: 1,
maximum: 100,
},
offset: {
type: 'number',
description: 'Pagination offset. Default 0.',
default: 0,
minimum: 0,
},
},
},
},
{
name: 'validate_workflow',
description: `Full workflow validation: structure, connections, expressions, AI tools. Returns errors/warnings/fixes. Essential before deploy.`,