convez.ai
PluginAutomaçãoIntermediário
Souzix76

n8n Workflow Tester Safe

Souzix76/n8n-workflow-tester-safe

Tester seguro para n8n sem risco de credenciais ou auto-fix destrutivos

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server e CLI para testar, inspecionar e validar workflows do n8n com escopo restrito e seguro. Oferece suites de testes com scoring configurável, rastreamento de execução e catálogo de nós, sem expor credenciais ou operações destrutivas.

Instalação

$npx convez-ai Souzix76/n8n-workflow-tester-safe

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 3 semanas
Versão
v1.0.0
Issues abertas
0
Contribuidores
3

Casos de uso

  • Validar workflows em CI/CD com scoring automático
  • Inspecionar e diagnosticar erros de execução em ambientes compartilhados
  • Testar payloads webhook e comportamentos de nós sem admin access

Veredito

Ferramenta focada e bem pensada para quem precisa testar n8n de forma segura sem expor superfícies de risco. Excelente para pipelines de CI e ambientes onde admin access é proibido.

README

A tradução para o português deste README ainda está na fila.


Why?

Most n8n MCP integrations give you full admin access — credentials, destructive operations, auto-fix loops. That's fine for development, but risky for CI, shared environments, or autonomous agents.

n8n-workflow-tester-safe takes a different approach:

FeatureThis MCPFull admin MCPs
Test workflows with scoringYesNo
Execution traces (lightweight)YesNo
Node catalog with suggestionsYesNo
Credential managementExcludedYes
Secret lifecycleExcludedYes
Auto-fix loopsExcludedSome

Result: A focused tool that does testing and inspection really well, without the risk surface of a full admin wrapper.


Quick Start

1. Install

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

2. Configure

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. Run

As MCP server (for Claude, OpenClaw, or any MCP client):

node dist/index.js

As CLI (for scripts and CI):

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

MCP Client Configuration

Claude Code (~/.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 / Any MCP client

The server uses stdio transport — compatible with any MCP client that supports stdio.


How It Works

Test Config

Define your tests in a JSON file:

{
  "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"
    }
  ]
}

Scoring System

Every test run produces a two-tier score:

Final Score = (Tier 1 x 70%) + (Tier 3 x 30%)
TierWeightWhat it checks
Tier 1 (Infrastructure)70%HTTP success, timeout compliance, non-empty output
Tier 3 (Quality)30%Custom field checks: contains, equals, min/max length, not_empty

A test passes when:

  • Tier 1 score = 100 (all infrastructure checks pass)
  • Final score >= quality threshold (default 85)
  • No issues with severity error

Example Output

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

Tools Reference

Testing (3 tools)

ToolDescription
test_workflowRun a single payload test from a config file
evaluate_workflow_resultRun a test and return evaluation score + issues
run_workflow_suiteRun all payloads in a config, return per-payload scores

Workflow Operations (5 tools)

ToolDescription
create_workflowCreate a new workflow from JSON
update_workflowReplace an existing workflow by ID
delete_workflowDelete a workflow by ID
add_node_to_workflowAppend a node to an existing workflow
connect_nodesCreate a connection between two nodes

Introspection (5 tools)

ToolDescription
get_workflow_summaryCompact summary: node count, names, types, disabled status
list_node_typesList all available node types from the n8n instance
get_node_typeFull schema/metadata for a specific node type
list_executionsRecent executions, filterable by workflow and status
get_executionFull execution data by ID
get_execution_traceLightweight per-node trace — timing, errors, item counts

Catalog (5 tools)

ToolDescription
get_catalog_statsNode/trigger/credential counts from imported catalog
search_nodesFuzzy search by name, optional trigger-only filter
list_triggersAll trigger nodes from the catalog
validate_node_typeCheck if a node type exists, get close matches
suggest_nodes_for_taskNatural-language task in, relevant nodes out

Example Configs

The workflows/ directory includes ready-to-use test configs:

FileTrigger ModePayloadsDescription
example.jsonwebhook2Basic webhook echo test
telegram-bot.jsonwebhook3Telegram bot command handler
api-pipeline.jsonexecute3Multi-step API data pipeline

Architecture

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

Design Constraints

  • stdio-only transport — no HTTP server, no auth to manage
  • Explicit tool surface — 19 tools, each with a clear purpose
  • Small dependency footprint — only @modelcontextprotocol/sdk and zod
  • No credential lifecycle — won't read, create, or delete credentials
  • No agentic auto-repair — reports issues, doesn't auto-fix them

Safety Posture

Included

  • Workflow test execution (webhook + API)
  • Output evaluation with tiered scoring
  • Workflow CRUD (create, read, update, delete)
  • Graph editing (add nodes, connect)
  • Execution inspection and tracing
  • Node catalog lookup and validation

Deliberately Excluded

  • Credentials management
  • Secrets lifecycle
  • Destructive restore flows
  • Autonomous LLM auto-fix loops
  • Production deployment operations

Roadmap

  • Read-only mode flag (disable all mutation tools)
  • Workflow diff summaries (before/after comparison)
  • Reusable evaluation presets for common patterns
  • Richer trace visualization
  • Fixture libraries for test payloads
  • npm package for npx usage

Contributing

  1. Fork the repo
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Commit changes (git commit -m 'feat: add my feature')
  4. Push to branch (git push origin feat/my-feature)
  5. Open a Pull Request

License

MIT


Ver o original no GitHub

Bom para

Relacionados