n8n-mcp 模板集成模块深度解析从 n8n.io 抓取、存储到 MCP 工具调用的完整实战指南【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读本文以 src/templates/README.md 为骨架结合 n8n-mcp 仓库中模板抓取、存储、检索与 MCP 工具层的完整实现系统讲解该模块如何让 AI AgentClaude Desktop / Claude Code / Windsurf / Cursor发现并复用 n8n.io 上经过验证的工作流模板。读完本文你将掌握模板数据的完整生命周期——从 n8n.io 官方 API 的分页抓取与限速策略、SQLite 本地存储与 gzip 压缩、FTS5 全文检索与任务分类映射到list_node_templates、get_template、search_templates、get_templates_for_task四个 MCP 工具的实际调用方式与参数细节并了解 AI 元数据增强这一进阶能力。模块定位与核心能力模板集成模块Templates Integration解决的是 AI Agent 构建 n8n 工作流时的从零开始难题与其每次让 Agent 凭空设计工作流结构不如让它先检索社区中已经过验证的成熟模板再基于真实工作流 JSON 进行定制。该模块的核心能力包括API 集成直连 n8n.io 官方模板 APIhttps://api.n8n.io/api/templates而非手动维护模板数据新鲜度约束默认只收录创建时间在近 12 个月内的模板README 描述的 6 个月窗口在 template-fetcher.ts 中实际实现为默认 12 个月的cutoffDate可通过sinceDate参数覆盖保证 Agent 接触的是当下社区正在使用的模式而非过时方案独立抓取模板数据与主节点数据库nodes.db分离管理不参与常规的数据库重建流程需要显式运行fetch:templates命令手动更新完整工作流 JSON每个模板都保存了可直接导入 n8n 的完整 workflow 定义nodes connections settings而非仅有元数据摘要智能检索支持按节点类型、关键词、任务分类、元数据字段复杂度、所需服务、目标人群等多种维度搜索。从源码结构看模块由三个核心文件构成template-fetcher.tsAPI 通信与限速、template-repository.ts数据库操作与查询、template-service.ts业务逻辑与 MCP 集成另有metadata-generator.ts、batch-processor.ts、sequential-processor.ts三个文件支撑 AI 元数据增强能力。数据抓取n8n.io API 的工程化访问抓取流程概览执行npm run fetch:templates后fetch-templates.ts 脚本会驱动TemplateFetcher完成以下步骤连接 n8n.io 模板 API分页拉取全部模板列表再按日期过滤出近期模板逐个下载每个模板的完整工作流 JSON清洗移除 API Token、压缩后写入本地 SQLite 数据库打印进度与统计信息每个阶段的当前值/总数通过progressCallback上报。分页与速率控制template-fetcher.ts 中定义了关键抓取参数参数值说明baseUrlhttps://api.n8n.io/api/templates模板 API 基地址pageSize250每页条数注释标明是 API 允许的最大值maxRetries3单页失败最大重试次数retryDelay1000ms指数退避的基础延迟抓取列表时代码以while (hasMore)循环翻页通过workflows.length pageSize判断是否还有下一页template-fetcher.ts。源码注释记录了一个重要事实sort_by参数在该 API 上不生效模板按热度popularity顺序返回——这意味着排在前面的是社区浏览最多的模板恰好与后续按浏览量排序的本地策略互补。限速策略是对 API 友好的关键列表页之间休眠300ms源码注释说明从早期每页 100 条时的 500ms 下调而来详情抓取每请求之间休眠150ms。所有请求都经过retryWithBackoff包装失败后按1000ms × attempt指数退避重试3 次仍失败则跳过该页/该模板并记录警告日志不会让整个抓取流程中断。新鲜度过滤与增量更新fetchTemplates(progressCallback, sinceDate)采用先全量拉取、后本地过滤的策略先抓完所有分页再用日期截断值过滤。sinceDate不传时默认取当前时间前 12 个月template-fetcher.ts。在TemplateService.fetchAndUpdateTemplatestemplate-service.ts中两种抓取模式的区别非常清晰rebuild 模式默认先clearTemplates()清空表再全量重建最后调用rebuildTemplateFTS()重建 FTS5 索引update 模式--modeupdate或--update读取库中已有模板 ID 集合与最近创建日期只抓取最近一条模板创建时间往前推 14 天以来的新模板并与现有 ID 做差集去重实现低成本增量更新。命令行使用方式package.json中定义了完整的模板相关脚本package.jsonnpm run fetch:templates # 全量重建模式抓取模板 npm run fetch:templates:update # 增量更新模式--update 简写 npm run fetch:templates:extract # 仅提取节点配置跳过模板抓取 npm run fetch:templates:robust # 稳健版抓取脚本 npm run test:templates # 运行模板相关测试fetch-templates.ts的命令行参数见其parseArgs函数与帮助输出--moderebuild|update 重建或增量更新默认 rebuild --update 等价于 --modeupdate --generate-metadata / --metadata 抓取后生成 AI 元数据 --metadata-only 只生成元数据跳过模板抓取 --extract-only / --extract 只从已有模板中提取节点配置跳过抓取--extract-only对应的能力是把热门模板中真实使用的节点配置抽取到template_node_configs表为 Agent 提供经过实战验证的配置示例--metadata-only则聚焦于元数据补充两种模式都避免重复访问 API。本地存储数据库设计与数据安全表结构模板存储在templates表中schema.sql 定义了完整字段字段类型说明idINTEGER PK模板 IDworkflow_idINTEGER UNIQUEn8n.io 工作流 ID与 id 相同name/descriptionTEXT名称与描述author_name/author_username/author_verifiedTEXT / INTEGER作者信息nodes_usedTEXT节点类型 JSON 数组workflow_jsonTEXT完整工作流 JSON已废弃见下workflow_json_compressedTEXTBase64 编码的 gzip 压缩工作流categoriesTEXT分类 JSON 数组viewsINTEGER浏览量用于热度排序created_at/updated_at/scraped_atDATETIME时间戳urlTEXTn8n.io 上的模板链接metadata_json/metadata_generated_atTEXT / DATETIMEAI 生成的结构化元数据配套索引覆盖了nodes_used、updated_at、name、metadata_generated_at四个高频查询维度。抓取脚本在 rebuild 模式下会先 DROP 旧表再重建update 模式下则做轻量迁移自动检查并补加metadata_json、metadata_generated_at列兼容旧版本数据库。压缩存储与浏览量过滤存储层有两个值得注意的设计template-repository.ts浏览量门槛totalViews 10的模板直接跳过不保存从源头过滤掉几乎没有社区验证的模板gzip 压缩完整工作流 JSON 经TemplateSanitizer清洗后用zlib.gzipSync压缩再转 Base64 存入workflow_json_compressed字段workflow_json明文字段已废弃读取时按需解压。源码在保存时计算压缩率并记录日志显著降低了大工作流 JSON 的磁盘占用。安全清洗防止凭据泄漏TemplateSanitizertemplate-sanitizer.ts在入库前对每个工作流执行安全检查按已知模式检测并移除 API Token内置模式包括 OpenAI 的sk-前缀 Token、GitHub OAuth Tokengho_开头 36 位以上、通用BearerToken并支持通过addProblematicToken/addTokenPattern动态扩展删除pinData含敏感执行数据、executionId、staticData等工作流运行时字段若检测到并清除了 Token会在日志中记录模板 ID、名称与 Token 预览截取前 20 字符方便追溯。这意味着即使社区模板作者误提交了真实凭据本地库中保存的也是脱敏版本Agent 拿到的模板不会携带他人密钥。智能检索从 FTS5 全文搜索到多维过滤全文搜索FTS5 优先LIKE 兜底TemplateRepository.searchTemplatestemplate-repository.ts在初始化时检测 SQLite 是否支持 FTS5checkFTS5Support支持则创建templates_fts虚拟表并通过三个触发器insert/update/delete与templates表保持同步。查询时把用户关键词按空格拆分、逐个加双引号转义后用OR连接成 FTS 查询按rank相关性views DESC排序若 FTS5 不可用或查询抛错自动回退到name LIKE %query% OR description LIKE %query%的 LIKE 搜索。批量导入后会执行rebuildTemplateFTS()重建索引防止 FTS 与源表失步。节点类型解析兼容各种输入格式模板库中节点类型统一存为完整 n8n 格式如n8n-nodes-base.slack而 Agent 可能用各种简写slack、nodes-base.webhook、httpRequest发起查询。resolveTemplateNodeTypestemplate-node-resolver.ts负责把输入展开为所有可能的匹配变体——裸名会同时尝试n8n-nodes-base与n8n/n8n-nodes-langchain两个包名并补充驼峰变体如webhook→webhookTrigger、httpRequest。随后用nodes_used LIKE %node%的 JSON 数组匹配方式检索保证查询命中率。任务分类映射语义化检索的桥梁getTemplatesForTasktemplate-repository.ts把抽象任务名映射到具体节点组合const taskNodeMap: Recordstring, string[] { ai_automation: [n8n/n8n-nodes-langchain.openAi, n8n/n8n-nodes-langchain.agent, n8n-nodes-base.openAi], data_sync: [n8n-nodes-base.googleSheets, n8n-nodes-base.postgres, n8n-nodes-base.mysql], webhook_processing: [n8n-nodes-base.webhook], // 只匹配 webhook 触发 email_automation: [n8n-nodes-base.gmail, n8n-nodes-base.emailSend, n8n-nodes-base.emailReadImap], slack_integration: [n8n-nodes-base.slack, n8n-nodes-base.slackTrigger], data_transformation: [n8n-nodes-base.code, n8n-nodes-base.set, n8n-nodes-base.merge], file_processing: [n8n-nodes-base.readBinaryFile, n8n-nodes-base.writeBinaryFile, n8n-nodes-base.googleDrive], scheduling: [n8n-nodes-base.scheduleTrigger, n8n-nodes-base.cron], api_integration: [n8n-nodes-base.httpRequest, n8n-nodes-base.graphql], database_operations: [n8n-nodes-base.postgres, n8n-nodes-base.mysql, n8n-nodes-base.mongodb] };源码注释记录了一个 QA 结论webhook_processing若把httpRequest也纳入映射会误召回仅用出站 HTTP 请求的 schedule/form 触发工作流因此该分类只保留n8n-nodes-base.webhook触发节点。这体现了任务分类映射是经过实际检索质量校验的而非简单关键词堆砌。元数据过滤按复杂度、耗时、服务过滤对于已启用 AI 元数据增强的模板searchTemplatesByMetadatatemplate-repository.ts支持按category、complexitysimple/medium/complex、maxSetupMinutes/minSetupMinutes5–480 分钟、requiredService、targetAudience过滤。其实现采用两阶段查询优化第一阶段只查id列不加载大体积压缩工作流避免无过滤条件下的超时第二阶段用WITH ordered_ids(id, sort_order) AS (VALUES ...)的 CTE 按第一阶段顺序取回完整记录并在日志中记录两阶段各自耗时。MCP 工具层Agent 的模板检索入口四大核心工具模块通过 MCP 暴露四个模板工具。search_templates在 server.ts 中已演化为带searchMode的统一入口覆盖其余三个工具的检索能力工具参数说明list_node_templates(nodeTypes, limit)nodeTypes: string[]limit默认 10按节点类型找模板入参经节点解析器展开变体get_template(templateId, mode)mode:nodes_only/structure/full默认 full获取完整工作流 JSON可直接导入 n8nsearch_templates(query, limit, fields)见下文 searchMode 变体关键词全文搜索可指定返回字段get_templates_for_task(task, limit)task: 十种预定义任务名按任务分类返回策划好的模板search_templates 的五种模式search_templates通过searchMode参数收敛为一个工具search-templates.tskeyword默认跨名称/描述全文搜索需传query可选fields限制返回字段id、name、description、author、nodes、views、created、url、metadataby_nodes按节点类型查找需传nodeTypes数组如[n8n-nodes-base.httpRequest, n8n-nodes-base.slack]by_task按任务分类查找需传taskby_metadata结构化元数据过滤支持category、complexity、maxSetupMinutes、minSetupMinutes、requiredService、targetAudiencepatterns跨全部模板挖掘的轻量工作流模式摘要节点频率 连接链可传task限定类别。limit会被钳制在 1–100 之间默认 20offset用于分页返回结构统一为{ items, total, limit, offset, hasMore }的分页响应。get_template 的三种详情粒度get_template的mode参数控制返回的工作流信息量get-template.tsnodes_only仅返回节点列表type name适合快速了解模板构成structure返回节点含 id、type、name、position与connections拓扑适合分析流程结构full默认返回完整workflownodes 含 parameters、connections、settings可直接导入 n8n。该工具是纯本地数据库查找文档标注单次查询毫秒级完成、无网络调用。工具文档还给出实用建议模板 ID 会随数据库刷新而变化应从search_templates的结果中获取模板中的凭据是占位符导入后需自行配置。AI 元数据增强让模板可被结构化理解结构化输出 Schema为了弥补模板本身只有名称、描述、节点列表的局限模块用 OpenAI 结构化输出为模板生成七类元数据metadata-generator.tscategories主分类最多 5 个complexity实现复杂度simple / medium / complexuse_cases主要使用场景最多 5 个estimated_setup_minutes预估搭建耗时5–480 分钟required_services需要的外部服务/API明确排除 n8n 本身key_features主要能力最多 5 个target_audience目标人群最多 3 个如 developers、marketers。Schema 用 Zod 定义并通过response_format: { type: json_schema }强制模型输出合规 JSON解析后再经TemplateMetadataSchema.parse二次校验失败则回退到默认元数据automation/medium/ 30 分钟等。输入净化与两种处理通道生成请求前模板名称与描述会经过sanitizeInput处理截断长度名称 200 字符、描述 500 字符、剥离控制字符、压缩空白并移除system:/assistant:等提示注入模式与代码块标记系统提示词也明确要求模型只输出 schema 要求的 JSON绝不回显输入降低提示注入风险。节点列表则先经summarizeNodes归类汇总HTTP/Webhooks、Database、Communication、AI/ML、Spreadsheets 等分组控制 token 消耗。处理通道有两种OpenAI Batch APIbatch-processor.ts把模板分批默认每批 100 个写成 JSONL 上传创建/v1/chat/completionsbatch 任务completion_window: 24h每 60 秒轮询状态最长 120 分钟完成后下载输出文件解析结果、对失败请求生成默认元数据并自动清理本地与远端文件Direct 直连模式sequential-processor.ts针对 vLLM、Ollama 等不实现/v1/batches端点的 OpenAI 兼容服务器用chat.completions.create()以默认 40 并发直接调用支持通过N8N_MCP_LLM_BASE_URL配置本地模型地址。测试与质量保障模板模块有完整的测试覆盖集成测试 template-repository.test.ts 验证了保存/更新去重、复杂节点类型处理、FTS5 检索、任务映射等行为metadata-operations.test.ts 覆盖元数据生成与更新fetch-templates-extraction.test.ts 验证配置提取逻辑另有数据库性能测试对模板检索进行基准验证。运行npm run test:templates即可执行相关用例。注意事项与最佳实践模板不参与常规数据库重建抓取节点数据库不会顺带更新模板需要新模板时显式运行npm run fetch:templates或增量模式npm run fetch:templates:updateAPI 限速已内置列表页间 300ms、详情间 150ms 的休眠与 3 次指数退避重试可避免触发 n8n.io 节流大批量抓取时终端会实时显示进度与统计大体积数据集有进度反馈抓取列表、下载详情、生成元数据三个阶段都有progressCallback向命令行输出进度便于观察长任务状态模板 ID 不稳定数据库刷新后 ID 会变化工作流应先通过search_templates获取 ID 再调用get_template不要把 ID 硬编码导入前检查兼容性部分模板可能使用已废弃的节点版本或引用你没有的外部服务导入前先查看创建时间与required_services元数据并确认相关凭据已就绪凭据为占位符模板中的 API Key 等凭据在入库时已被TemplateSanitizer清除导入后必须配置自己的凭据。从整体架构看该模块构成了 n8n-mcp 中模板发现 → 结构理解 → 工作流导入的闭环Agent 先用search_templates定位合适的模板再用get_template的structure模式理解拓扑、full模式获取可导入 JSON最终借助n8n_create_workflow等管理工具落地到实际 n8n 实例让社区验证过的工作流模式真正成为 AI 构建能力的素材库。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 n8n-mcp 模板集成模块深度解析：从 n8n.io 抓取、存储到 MCP 工具调用的完整实战指南
n8n-mcp 模板集成模块深度解析从 n8n.io 抓取、存储到 MCP 工具调用的完整实战指南【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读本文以 src/templates/README.md 为骨架结合 n8n-mcp 仓库中模板抓取、存储、检索与 MCP 工具层的完整实现系统讲解该模块如何让 AI AgentClaude Desktop / Claude Code / Windsurf / Cursor发现并复用 n8n.io 上经过验证的工作流模板。读完本文你将掌握模板数据的完整生命周期——从 n8n.io 官方 API 的分页抓取与限速策略、SQLite 本地存储与 gzip 压缩、FTS5 全文检索与任务分类映射到list_node_templates、get_template、search_templates、get_templates_for_task四个 MCP 工具的实际调用方式与参数细节并了解 AI 元数据增强这一进阶能力。模块定位与核心能力模板集成模块Templates Integration解决的是 AI Agent 构建 n8n 工作流时的从零开始难题与其每次让 Agent 凭空设计工作流结构不如让它先检索社区中已经过验证的成熟模板再基于真实工作流 JSON 进行定制。该模块的核心能力包括API 集成直连 n8n.io 官方模板 APIhttps://api.n8n.io/api/templates而非手动维护模板数据新鲜度约束默认只收录创建时间在近 12 个月内的模板README 描述的 6 个月窗口在 template-fetcher.ts 中实际实现为默认 12 个月的cutoffDate可通过sinceDate参数覆盖保证 Agent 接触的是当下社区正在使用的模式而非过时方案独立抓取模板数据与主节点数据库nodes.db分离管理不参与常规的数据库重建流程需要显式运行fetch:templates命令手动更新完整工作流 JSON每个模板都保存了可直接导入 n8n 的完整 workflow 定义nodes connections settings而非仅有元数据摘要智能检索支持按节点类型、关键词、任务分类、元数据字段复杂度、所需服务、目标人群等多种维度搜索。从源码结构看模块由三个核心文件构成template-fetcher.tsAPI 通信与限速、template-repository.ts数据库操作与查询、template-service.ts业务逻辑与 MCP 集成另有metadata-generator.ts、batch-processor.ts、sequential-processor.ts三个文件支撑 AI 元数据增强能力。数据抓取n8n.io API 的工程化访问抓取流程概览执行npm run fetch:templates后fetch-templates.ts 脚本会驱动TemplateFetcher完成以下步骤连接 n8n.io 模板 API分页拉取全部模板列表再按日期过滤出近期模板逐个下载每个模板的完整工作流 JSON清洗移除 API Token、压缩后写入本地 SQLite 数据库打印进度与统计信息每个阶段的当前值/总数通过progressCallback上报。分页与速率控制template-fetcher.ts 中定义了关键抓取参数参数值说明baseUrlhttps://api.n8n.io/api/templates模板 API 基地址pageSize250每页条数注释标明是 API 允许的最大值maxRetries3单页失败最大重试次数retryDelay1000ms指数退避的基础延迟抓取列表时代码以while (hasMore)循环翻页通过workflows.length pageSize判断是否还有下一页template-fetcher.ts。源码注释记录了一个重要事实sort_by参数在该 API 上不生效模板按热度popularity顺序返回——这意味着排在前面的是社区浏览最多的模板恰好与后续按浏览量排序的本地策略互补。限速策略是对 API 友好的关键列表页之间休眠300ms源码注释说明从早期每页 100 条时的 500ms 下调而来详情抓取每请求之间休眠150ms。所有请求都经过retryWithBackoff包装失败后按1000ms × attempt指数退避重试3 次仍失败则跳过该页/该模板并记录警告日志不会让整个抓取流程中断。新鲜度过滤与增量更新fetchTemplates(progressCallback, sinceDate)采用先全量拉取、后本地过滤的策略先抓完所有分页再用日期截断值过滤。sinceDate不传时默认取当前时间前 12 个月template-fetcher.ts。在TemplateService.fetchAndUpdateTemplatestemplate-service.ts中两种抓取模式的区别非常清晰rebuild 模式默认先clearTemplates()清空表再全量重建最后调用rebuildTemplateFTS()重建 FTS5 索引update 模式--modeupdate或--update读取库中已有模板 ID 集合与最近创建日期只抓取最近一条模板创建时间往前推 14 天以来的新模板并与现有 ID 做差集去重实现低成本增量更新。命令行使用方式package.json中定义了完整的模板相关脚本package.jsonnpm run fetch:templates # 全量重建模式抓取模板 npm run fetch:templates:update # 增量更新模式--update 简写 npm run fetch:templates:extract # 仅提取节点配置跳过模板抓取 npm run fetch:templates:robust # 稳健版抓取脚本 npm run test:templates # 运行模板相关测试fetch-templates.ts的命令行参数见其parseArgs函数与帮助输出--moderebuild|update 重建或增量更新默认 rebuild --update 等价于 --modeupdate --generate-metadata / --metadata 抓取后生成 AI 元数据 --metadata-only 只生成元数据跳过模板抓取 --extract-only / --extract 只从已有模板中提取节点配置跳过抓取--extract-only对应的能力是把热门模板中真实使用的节点配置抽取到template_node_configs表为 Agent 提供经过实战验证的配置示例--metadata-only则聚焦于元数据补充两种模式都避免重复访问 API。本地存储数据库设计与数据安全表结构模板存储在templates表中schema.sql 定义了完整字段字段类型说明idINTEGER PK模板 IDworkflow_idINTEGER UNIQUEn8n.io 工作流 ID与 id 相同name/descriptionTEXT名称与描述author_name/author_username/author_verifiedTEXT / INTEGER作者信息nodes_usedTEXT节点类型 JSON 数组workflow_jsonTEXT完整工作流 JSON已废弃见下workflow_json_compressedTEXTBase64 编码的 gzip 压缩工作流categoriesTEXT分类 JSON 数组viewsINTEGER浏览量用于热度排序created_at/updated_at/scraped_atDATETIME时间戳urlTEXTn8n.io 上的模板链接metadata_json/metadata_generated_atTEXT / DATETIMEAI 生成的结构化元数据配套索引覆盖了nodes_used、updated_at、name、metadata_generated_at四个高频查询维度。抓取脚本在 rebuild 模式下会先 DROP 旧表再重建update 模式下则做轻量迁移自动检查并补加metadata_json、metadata_generated_at列兼容旧版本数据库。压缩存储与浏览量过滤存储层有两个值得注意的设计template-repository.ts浏览量门槛totalViews 10的模板直接跳过不保存从源头过滤掉几乎没有社区验证的模板gzip 压缩完整工作流 JSON 经TemplateSanitizer清洗后用zlib.gzipSync压缩再转 Base64 存入workflow_json_compressed字段workflow_json明文字段已废弃读取时按需解压。源码在保存时计算压缩率并记录日志显著降低了大工作流 JSON 的磁盘占用。安全清洗防止凭据泄漏TemplateSanitizertemplate-sanitizer.ts在入库前对每个工作流执行安全检查按已知模式检测并移除 API Token内置模式包括 OpenAI 的sk-前缀 Token、GitHub OAuth Tokengho_开头 36 位以上、通用BearerToken并支持通过addProblematicToken/addTokenPattern动态扩展删除pinData含敏感执行数据、executionId、staticData等工作流运行时字段若检测到并清除了 Token会在日志中记录模板 ID、名称与 Token 预览截取前 20 字符方便追溯。这意味着即使社区模板作者误提交了真实凭据本地库中保存的也是脱敏版本Agent 拿到的模板不会携带他人密钥。智能检索从 FTS5 全文搜索到多维过滤全文搜索FTS5 优先LIKE 兜底TemplateRepository.searchTemplatestemplate-repository.ts在初始化时检测 SQLite 是否支持 FTS5checkFTS5Support支持则创建templates_fts虚拟表并通过三个触发器insert/update/delete与templates表保持同步。查询时把用户关键词按空格拆分、逐个加双引号转义后用OR连接成 FTS 查询按rank相关性views DESC排序若 FTS5 不可用或查询抛错自动回退到name LIKE %query% OR description LIKE %query%的 LIKE 搜索。批量导入后会执行rebuildTemplateFTS()重建索引防止 FTS 与源表失步。节点类型解析兼容各种输入格式模板库中节点类型统一存为完整 n8n 格式如n8n-nodes-base.slack而 Agent 可能用各种简写slack、nodes-base.webhook、httpRequest发起查询。resolveTemplateNodeTypestemplate-node-resolver.ts负责把输入展开为所有可能的匹配变体——裸名会同时尝试n8n-nodes-base与n8n/n8n-nodes-langchain两个包名并补充驼峰变体如webhook→webhookTrigger、httpRequest。随后用nodes_used LIKE %node%的 JSON 数组匹配方式检索保证查询命中率。任务分类映射语义化检索的桥梁getTemplatesForTasktemplate-repository.ts把抽象任务名映射到具体节点组合const taskNodeMap: Recordstring, string[] { ai_automation: [n8n/n8n-nodes-langchain.openAi, n8n/n8n-nodes-langchain.agent, n8n-nodes-base.openAi], data_sync: [n8n-nodes-base.googleSheets, n8n-nodes-base.postgres, n8n-nodes-base.mysql], webhook_processing: [n8n-nodes-base.webhook], // 只匹配 webhook 触发 email_automation: [n8n-nodes-base.gmail, n8n-nodes-base.emailSend, n8n-nodes-base.emailReadImap], slack_integration: [n8n-nodes-base.slack, n8n-nodes-base.slackTrigger], data_transformation: [n8n-nodes-base.code, n8n-nodes-base.set, n8n-nodes-base.merge], file_processing: [n8n-nodes-base.readBinaryFile, n8n-nodes-base.writeBinaryFile, n8n-nodes-base.googleDrive], scheduling: [n8n-nodes-base.scheduleTrigger, n8n-nodes-base.cron], api_integration: [n8n-nodes-base.httpRequest, n8n-nodes-base.graphql], database_operations: [n8n-nodes-base.postgres, n8n-nodes-base.mysql, n8n-nodes-base.mongodb] };源码注释记录了一个 QA 结论webhook_processing若把httpRequest也纳入映射会误召回仅用出站 HTTP 请求的 schedule/form 触发工作流因此该分类只保留n8n-nodes-base.webhook触发节点。这体现了任务分类映射是经过实际检索质量校验的而非简单关键词堆砌。元数据过滤按复杂度、耗时、服务过滤对于已启用 AI 元数据增强的模板searchTemplatesByMetadatatemplate-repository.ts支持按category、complexitysimple/medium/complex、maxSetupMinutes/minSetupMinutes5–480 分钟、requiredService、targetAudience过滤。其实现采用两阶段查询优化第一阶段只查id列不加载大体积压缩工作流避免无过滤条件下的超时第二阶段用WITH ordered_ids(id, sort_order) AS (VALUES ...)的 CTE 按第一阶段顺序取回完整记录并在日志中记录两阶段各自耗时。MCP 工具层Agent 的模板检索入口四大核心工具模块通过 MCP 暴露四个模板工具。search_templates在 server.ts 中已演化为带searchMode的统一入口覆盖其余三个工具的检索能力工具参数说明list_node_templates(nodeTypes, limit)nodeTypes: string[]limit默认 10按节点类型找模板入参经节点解析器展开变体get_template(templateId, mode)mode:nodes_only/structure/full默认 full获取完整工作流 JSON可直接导入 n8nsearch_templates(query, limit, fields)见下文 searchMode 变体关键词全文搜索可指定返回字段get_templates_for_task(task, limit)task: 十种预定义任务名按任务分类返回策划好的模板search_templates 的五种模式search_templates通过searchMode参数收敛为一个工具search-templates.tskeyword默认跨名称/描述全文搜索需传query可选fields限制返回字段id、name、description、author、nodes、views、created、url、metadataby_nodes按节点类型查找需传nodeTypes数组如[n8n-nodes-base.httpRequest, n8n-nodes-base.slack]by_task按任务分类查找需传taskby_metadata结构化元数据过滤支持category、complexity、maxSetupMinutes、minSetupMinutes、requiredService、targetAudiencepatterns跨全部模板挖掘的轻量工作流模式摘要节点频率 连接链可传task限定类别。limit会被钳制在 1–100 之间默认 20offset用于分页返回结构统一为{ items, total, limit, offset, hasMore }的分页响应。get_template 的三种详情粒度get_template的mode参数控制返回的工作流信息量get-template.tsnodes_only仅返回节点列表type name适合快速了解模板构成structure返回节点含 id、type、name、position与connections拓扑适合分析流程结构full默认返回完整workflownodes 含 parameters、connections、settings可直接导入 n8n。该工具是纯本地数据库查找文档标注单次查询毫秒级完成、无网络调用。工具文档还给出实用建议模板 ID 会随数据库刷新而变化应从search_templates的结果中获取模板中的凭据是占位符导入后需自行配置。AI 元数据增强让模板可被结构化理解结构化输出 Schema为了弥补模板本身只有名称、描述、节点列表的局限模块用 OpenAI 结构化输出为模板生成七类元数据metadata-generator.tscategories主分类最多 5 个complexity实现复杂度simple / medium / complexuse_cases主要使用场景最多 5 个estimated_setup_minutes预估搭建耗时5–480 分钟required_services需要的外部服务/API明确排除 n8n 本身key_features主要能力最多 5 个target_audience目标人群最多 3 个如 developers、marketers。Schema 用 Zod 定义并通过response_format: { type: json_schema }强制模型输出合规 JSON解析后再经TemplateMetadataSchema.parse二次校验失败则回退到默认元数据automation/medium/ 30 分钟等。输入净化与两种处理通道生成请求前模板名称与描述会经过sanitizeInput处理截断长度名称 200 字符、描述 500 字符、剥离控制字符、压缩空白并移除system:/assistant:等提示注入模式与代码块标记系统提示词也明确要求模型只输出 schema 要求的 JSON绝不回显输入降低提示注入风险。节点列表则先经summarizeNodes归类汇总HTTP/Webhooks、Database、Communication、AI/ML、Spreadsheets 等分组控制 token 消耗。处理通道有两种OpenAI Batch APIbatch-processor.ts把模板分批默认每批 100 个写成 JSONL 上传创建/v1/chat/completionsbatch 任务completion_window: 24h每 60 秒轮询状态最长 120 分钟完成后下载输出文件解析结果、对失败请求生成默认元数据并自动清理本地与远端文件Direct 直连模式sequential-processor.ts针对 vLLM、Ollama 等不实现/v1/batches端点的 OpenAI 兼容服务器用chat.completions.create()以默认 40 并发直接调用支持通过N8N_MCP_LLM_BASE_URL配置本地模型地址。测试与质量保障模板模块有完整的测试覆盖集成测试 template-repository.test.ts 验证了保存/更新去重、复杂节点类型处理、FTS5 检索、任务映射等行为metadata-operations.test.ts 覆盖元数据生成与更新fetch-templates-extraction.test.ts 验证配置提取逻辑另有数据库性能测试对模板检索进行基准验证。运行npm run test:templates即可执行相关用例。注意事项与最佳实践模板不参与常规数据库重建抓取节点数据库不会顺带更新模板需要新模板时显式运行npm run fetch:templates或增量模式npm run fetch:templates:updateAPI 限速已内置列表页间 300ms、详情间 150ms 的休眠与 3 次指数退避重试可避免触发 n8n.io 节流大批量抓取时终端会实时显示进度与统计大体积数据集有进度反馈抓取列表、下载详情、生成元数据三个阶段都有progressCallback向命令行输出进度便于观察长任务状态模板 ID 不稳定数据库刷新后 ID 会变化工作流应先通过search_templates获取 ID 再调用get_template不要把 ID 硬编码导入前检查兼容性部分模板可能使用已废弃的节点版本或引用你没有的外部服务导入前先查看创建时间与required_services元数据并确认相关凭据已就绪凭据为占位符模板中的 API Key 等凭据在入库时已被TemplateSanitizer清除导入后必须配置自己的凭据。从整体架构看该模块构成了 n8n-mcp 中模板发现 → 结构理解 → 工作流导入的闭环Agent 先用search_templates定位合适的模板再用get_template的structure模式理解拓扑、full模式获取可导入 JSON最终借助n8n_create_workflow等管理工具落地到实际 n8n 实例让社区验证过的工作流模式真正成为 AI 构建能力的素材库。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考