N8n Workflow Tester Safe

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 采取了不同的方法：

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

______________________________________________________________________

快速开始

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%)

测试 通过 什么时候：

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

输出示例

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

______________________________________________________________________

工具参考

测试（3个工具）

工作流操作（5个工具）

内省（5个工具）

目录（5个工具）

______________________________________________________________________

配置示例

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

______________________________________________________________________

建筑

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 用法

______________________________________________________________________

贡献

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

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

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.