Name: n8n工作流测试工具
Author: Souzix76

使用说明

Safe MCP server + CLI for testing, scoring, and inspecting n8n workflows
Config-driven test suites with tiered scoring, execution traces, and a built-in node catalog.

为什么？

大多数n8n MCP集成都能为您提供 完全管理员权限 --凭证、破坏性操作、自动修复循环。这对开发来说很好，但对CI、共享环境或自主代理来说是有风险的。

n8n-workflow-tester-safe 采取了不同的方法：

功能	此MCP	完全管理MCP
带有评分的测试工作流程	是	否
执行跟踪（轻量级）	是	否
含建议的节点目录	是	否
凭证管理	排除	是的
秘密生命周期	排除	是的
自动修复循环	排除	一些

结果： 一个专注的工具，可以很好地进行测试和检查，没有完整的管理包装的风险表面。

快速开始

1.安装

git clone https://github.com/souzix76/n8n-workflow-tester-safe.git
cd n8n-workflow-tester-safe
npm install && npm run build

2.配置

cp .env.example .env
# Edit .env with your n8n URL and API key

N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=your_n8n_api_key_here
DEFAULT_TIMEOUT_MS=30000

3.跑步

作为MCP服务器 （适用于Claude、OpenClaw或任何MCP客户端）：

node dist/index.js

作为CLI （用于脚本和CI）：

node dist/cli.js --config ./workflows/example.json

MCP客户端配置

克劳德代码(`~/.claude.json`)

{
  "mcpServers": {
    "n8n-workflow-tester": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/n8n-workflow-tester-safe/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_api_key"
      }
    }
  }
}

OpenClaw/任何MCP客户端

服务器使用 stdio传输 --与任何支持stdio的MCP客户端兼容。

运作原理

测试配置

在JSON文件中定义测试：

{
  "workflowId": "abc123",
  "workflowName": "my-webhook-handler",
  "triggerMode": "webhook",
  "webhookPath": "/webhook/my-handler",
  "timeoutMs": 15000,
  "qualityThreshold": 85,
  "testPayloads": [
    {
      "name": "happy-path",
      "data": { "message": "Hello", "userId": "user_001" }
    },
    {
      "name": "empty-input",
      "data": { "message": "" }
    },
    {
      "name": "large-payload",
      "data": { "items": ["a","b","c","d","e","f","g","h","i","j"] }
    }
  ],
  "tier3Checks": [
    {
      "name": "has-response",
      "field": "output",
      "check": "not_empty",
      "severity": "error"
    },
    {
      "name": "response-length",
      "field": "output.message",
      "check": "min_length",
      "value": 5,
      "severity": "warning",
      "message": "Response too short"
    }
  ]
}

评分系统

每次测试运行都会产生一个 两级评分:

Final Score = (Tier 1 x 70%) + (Tier 3 x 30%)

层	重量	它检查什么
第1级（基础设施）	70%	HTTP成功，超时合规，非空输出
第3层（质量）	30%	自定义字段检查：包含、等于、最小/最大长度、非空

测试通过什么时候：

一级得分=100（所有基础设施检查均通过）
最终得分>=质量阈值（默认值85）
无严重性问题 error

输出示例

{
  "passed": true,
  "score": 93,
  "tier1Score": 100,
  "tier3Score": 80,
  "issues": [
    {
      "tier": "tier3",
      "severity": "warning",
      "check": "response-length",
      "message": "Response too short"
    }
  ]
}

工具参考

测试（3个工具）

工具	说明
`test_workflow`	从配置文件运行单个有效负载测试
`evaluate_workflow_result`	运行测试并返回评估分数+问题
`run_workflow_suite`	在配置中运行所有有效载荷，返回每个有效载荷的分数

工作流操作（5个工具）

工具	说明
`create_workflow`	从JSON创建新工作流
`update_workflow`	用ID替换现有工作流
`delete_workflow`	按ID删除工作流
`add_node_to_workflow`	将节点附加到现有工作流
`connect_nodes`	在两个节点之间创建连接

内省（5个工具）

工具	说明
`get_workflow_summary`	简明摘要：节点计数、名称、类型、禁用状态
`list_node_types`	列出n8n实例中的所有可用节点类型
`get_node_type`	特定节点类型的完整架构/元数据
`list_executions`	最近执行的操作，可按工作流和状态进行筛选
`get_execution`	按ID列出的完整执行数据
`get_execution_trace`	轻量级的每节点跟踪 --计时、错误、项目计数

目录（5个工具）

工具	说明
`get_catalog_stats`	导入目录中的节点/触发器/凭据计数
`search_nodes`	按名称模糊搜索，可选仅触发过滤器
`list_triggers`	目录中的所有触发节点
`validate_node_type`	检查节点类型是否存在，获取接近的匹配项
`suggest_nodes_for_task`	自然语言任务输入，相关节点输出

配置示例

这 workflows/ 目录包括现成的测试配置：

文件	触发模式	有效载荷	描述
`example.json`	webhook	2	基本webhook回声测试
`telegram-bot.json`	webhook	3	电报机器人命令处理程序
`api-pipeline.json`	执行	3	多步API数据管道

建筑

src/
  index.ts        MCP server (stdio) + tool registration
  cli.ts          CLI runner for config-driven tests
  n8n-client.ts   REST client for n8n API v1
  evaluator.ts    Two-tier scoring engine
  catalog.ts      Node catalog parser + fuzzy search
  config.ts       JSON config reader + Zod validation
  types.ts        TypeScript interfaces

catalog/          Imported n8n node catalog (436 nodes, 389 credentials)
workflows/        Example test suite configs

设计约束

仅限stdio传输 --无HTTP服务器，无需管理身份验证
显式工具曲面 --19个工具，每个工具都有明确的用途
依赖性占用空间小 --只有 @modelcontextprotocol/sdk 和 zod
无凭据生命周期 --不会读取、创建或删除凭据
无代理汽车维修 --报告问题，不自动修复

安全姿势

包含

工作流测试执行（webhook+API）
分级评分的产出评估
工作流CRUD（创建、读取、更新、删除）
图形编辑（添加节点、连接）
执行检查和跟踪
节点目录查找和验证

故意排除

凭证管理
秘密生命周期
破坏性恢复流
自主LLM自动修复循环
生产部署操作

路线图

[]只读模式标志（禁用所有变异工具）
[]工作流程差异总结（比较前后）
[]常见模式的可重用评估预设
[]更丰富的跟踪可视化
[]测试有效载荷的夹具库
[]npm包 npx 用法

贡献

分叉回购
创建要素分支(git checkout -b feat/my-feature)
提交更改(git commit -m 'feat: add my feature')
推送到分支(git push origin feat/my-feature)
打开拉取请求

许可证

麻省理工学院

Originally created by James (OpenClaw). Enhanced and maintained by Souzix76.
Built for n8n operators who want testing without the risk surface.
Compatible with Claude, OpenClaw, and any MCP client.