内容
<p align="center">
<img src="assets/banner.svg" alt="n8n-workflow-tester-safe" width="100%"/>
</p>
<p align="center">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-E8784A.svg" alt="License: MIT"/></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-D4A574.svg" alt="MCP Compatible"/></a>
<a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.7-blue.svg" alt="TypeScript"/></a>
<a href="https://n8n.io"><img src="https://img.shields.io/badge/n8n-2.12+-FF6D5A.svg" alt="n8n"/></a>
</p>
<p align="center">
<strong>安全MCP服务器和CLI，用于测试、评分和检查n8n工作流</strong><br/>
<em>基于配置的测试套件，支持分级评分、执行跟踪和内置节点目录。</em>
</p>
<a href="https://glama.ai/mcp/servers/Souzix76/n8n-workflow-tester-safe">
<img width="380" height="200" src="https://glama.ai/mcp/servers/Souzix76/n8n-workflow-tester-safe/badge" alt="n8n-workflow-tester-safe MCP server" />
</a>
---
## 为什么？
大多数n8n MCP集成提供**完全的管理权限** —— 凭证、破坏性操作、自动修复循环。对于开发来说，这没问题，但对于CI、共享环境或自治代理来说，风险太大。
`n8n-workflow-tester-safe`采取不同的方法：
| 功能 | 此MCP | 完全管理权限MCP |
|---------|----------|-----------------|
| 测试带有评分的工作流 | 是 | 否 |
| 执行跟踪（轻量级） | 是 | 否 |
| 节点目录和建议 | 是 | 否 |
| 凭证管理 | **排除** | 是 |
| 机密生命周期 | **排除** | 是 |
| 自动修复循环 | **排除** | 部分 |
**结果：** 一个专注于测试和检查的工具，无需完整的管理员权限。
---
## 快速开始
### 1. 安装
```bash
git clone https://github.com/souzix76/n8n-workflow-tester-safe.git
cd n8n-workflow-tester-safe
npm install && npm run build
```
### 2. 配置
```bash
cp .env.example .env
# 编辑.env文件，填写n8n URL和API密钥
```
```env
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客户端）：
```bash
node dist/index.js
```
**作为CLI** （适用于脚本和CI）：
```bash
node dist/cli.js --config ./workflows/example.json
```
---
## MCP客户端配置
### Claude代码（`~/.claude.json`）
```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文件中定义测试：
```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": "响应太短"
}
]
}
```
### 评分系统
每次测试运行都会产生一个**两级评分**：
```
最终评分 = (一级评分 * 70%) + (三级评分 * 30%)
```
| 级别 | 权重 | 检查内容 |
|------|--------|----------------|
| **一级** （基础设施） | 70% | HTTP成功、超时合规、非空输出 |
| **三级** （质量） | 30% | 自定义字段检查：包含、等于、最小/最大长度、非空 |
测试**通过**时：
- 一级评分 = 100（所有基础设施检查通过）
- 最终评分 >= 质量阈值（默认为85）
- 无严重性为`error`的问题
### 示例输出
```json
{
"passed": true,
"score": 93,
"tier1Score": 100,
"tier3Score": 80,
"issues": [
{
"tier": "tier3",
"severity": "warning",
"check": "response-length",
"message": "响应太短"
}
]
}
```
---
## 工具参考
### 测试（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 | Telegram机器人命令处理程序 |
| `api-pipeline.json` | execute | 3 | 多步骤API数据管道 |
---
## 架构
```
src/
index.ts MCP服务器（stdio）+ 工具注册
cli.ts CLI运行器，用于配置驱动的测试
n8n-client.ts n8n API v1的REST客户端
evaluator.ts 两级评分引擎
catalog.ts 节点目录解析器 + 模糊搜索
config.ts JSON配置读取器 + Zod验证
types.ts TypeScript接口
catalog/ 导入的n8n节点目录（436个节点，389个凭证）
workflows/ 示例测试套件配置
```
### 设计约束
- **仅stdio传输** —— 无HTTP服务器，无身份验证管理
- **显式工具表面** —— 19个工具，每个工具都有明确的用途
- **小依赖占用** —— 仅`@modelcontextprotocol/sdk`和`zod`
- **无凭证生命周期** —— 不读取、不创建或删除凭证
- **无代理自动修复** —— 报告问题，不自动修复
---
## 安全姿态
### 已包含
- 工作流测试执行（webhook + API）
- 输出评估，带有分级评分
- 工作流CRUD（创建、读取、更新、删除）
- 图形编辑（添加节点、连接）
- 执行检查和跟踪
- 节点目录查找和验证
### 故意排除
- 凭证管理
- 机密生命周期
- 破坏性恢复流程
- 自主LLM自动修复循环
- 生产部署操作
---
## 路线图
- [ ] 只读模式标志（禁用所有突变工具）
- [ ] 工作流差异摘要（前后比较）
- [ ] 可重用评估预设，用于常见模式
- [ ] 更丰富的跟踪可视化
- [ ] 测试有效载荷的Fixture库
- [ ] 用于`npx`使用的npm包
---
## 贡献
1. 分叉仓库
2. 创建功能分支（`git checkout -b feat/my-feature`）
3. 提交更改（`git commit -m 'feat: add my feature'`）
4. 推送到分支（`git push origin feat/my-feature`）
5. 打开拉取请求
---
## 许可证
[MIT](LICENSE)
---
<p align="center">
由James（<a href="https://openclaw.org">OpenClaw</a>）最初创建。由<a href="https://github.com/Souzix76">Souzix76</a>增强和维护。<br/>
为希望在无风险的情况下进行测试的<a href="https://n8n.io">n8n</a>操作员而建。<br/>
与<a href="https://claude.ai">Claude</a>、<a href="https://openclaw.org">OpenClaw</a>和任意MCP客户端兼容。
</p>
