深入解析salacoste/mcp-n8n-workflow-builder的OpenAPI规范

项目概述

salacoste/mcp-n8n-workflow-builder是一个基于n8n工作流自动化平台的扩展项目，它通过OpenAPI规范提供了完整的API接口定义。这个API允许开发者以编程方式管理n8n实例中的各种资源，包括工作流、凭证、执行记录等。

API基础信息

该OpenAPI规范采用3.0.0版本，定义了n8n公共API的完整接口。API基础路径为/api/v1，采用API密钥认证方式。规范中包含了丰富的元数据，如服务条款、联系方式和许可证信息。

主要功能模块

1. 工作流管理

工作流(Workflow)是n8n的核心概念，API提供了完整的CRUD操作：

• 创建工作流：通过POST请求提交工作流定义
• 获取工作流列表：支持按活跃状态、标签、名称等条件筛选
• 获取单个工作流：通过ID获取特定工作流详情
• 更新工作流：修改现有工作流配置
• 删除工作流：从系统中移除工作流
• 激活/停用工作流：控制工作流的运行状态

工作流API特别设计了excludePinnedData参数，允许控制是否返回固定数据，这在处理大型工作流时特别有用。

2. 凭证管理

凭证(Credential)管理模块允许程序化地处理各种认证信息：

• 创建凭证：为特定节点类型创建凭证
• 删除凭证：通过ID移除不再需要的凭证
• 获取凭证模式：查询特定凭证类型的数据结构

凭证API支持多种凭证类型，如Freshdesk API、Slack OAuth2等，每种类型都有严格的数据结构定义。

3. 执行记录管理

执行(Execution)记录API提供了对工作流运行历史的访问和控制：

• 获取执行列表：可按状态、工作流ID等条件筛选
• 获取单个执行：查询特定执行的详细信息
• 删除执行：清理执行记录

API支持分页查询，通过limit和cursor参数实现高效的数据获取。

4. 标签系统

标签(Tag)API为资源分类提供了支持：

• 创建标签：定义新的分类标签
• 获取标签：查询现有标签
• 更新标签：修改标签属性
• 删除标签：移除不再使用的标签

标签系统可以应用于工作流等多种资源，实现灵活的分类管理。

5. 安全检查

检查(Check)API提供了安全评估功能：

• 生成检查报告：分析系统安全状况
• 自定义检查选项：可配置废弃工作流判定天数、检查类别等

检查功能覆盖凭证、数据库、节点、文件系统和实例等多个安全维度。

技术特点

1. 标准化接口：严格遵循OpenAPI 3.0规范，确保接口一致性
2. 完善的错误处理：定义了401未授权、404未找到、500服务器错误等标准响应
3. 分页支持：列表接口普遍支持limit和cursor参数
4. 类型安全：每个接口都有明确的请求和响应模式定义
5. 模块化设计：按功能领域划分API端点，结构清晰

使用建议

1. 认证准备：确保已配置有效的API密钥
2. 错误处理：实现完善的错误处理逻辑，特别是401和404响应
3. 分页优化：处理大量数据时合理使用分页参数
4. 模式验证：创建资源前先获取相关模式定义，确保数据结构正确
5. 检查定期执行：建议定期调用检查API分析系统安全状况

总结

salacoste/mcp-n8n-workflow-builder的OpenAPI规范为n8n自动化平台提供了强大的程序化控制能力。通过这套API，开发者可以构建自定义的管理工具、监控系统或集成解决方案，实现n8n实例的全面自动化管理。规范的完整性和一致性使其成为企业级自动化解决方案的理想选择。