n8n Code-Based Toolkit

98% Token Savings | TypeScript-based n8n workflow management.

Replaces MCP server with direct TypeScript code execution for massive token efficiency gains.

Installation

npm install n8n-code-toolkit

Quick Start

import { createClient, listWorkflows, getWorkflowHealth, filterWorkflows, activateWorkflow, deleteWorkflow } from 'n8n-code-toolkit';

// Connect to n8n instance (reads N8N_URL + N8N_API_KEY from env)
const client = createClient();

// Check workflow health
const health = await getWorkflowHealth(client, 'workflow-123');
console.log(`Success rate: ${health.successRate}%`); // e.g., 98%

// Find production workflows
const prodWorkflows = await filterWorkflows(client, {
  tags: ['production'],
  metadataOnly: true // 90%+ smaller response
});

// Activate a workflow
await activateWorkflow(client, 'workflow-abc');

// Delete a workflow
await deleteWorkflow(client, 'workflow-xyz');

Progressive Disclosure Guide

Data returned at 4 levels - use the minimum you need:

| Level | Size | Use Case | Example | |-------|------|----------|---------| | name | 50B | Lists, dropdowns | Node search results | | description | 200B | Browse, preview | Template discovery | | essentials | 2KB | Planning, analysis | Workflow selection | | full | 20KB+ | Implementation | Deployment, editing |

Examples

// Level 1: Name only (~50 bytes)
const nodes = await searchNodes('slack', { detailLevel: 'name' });

// Level 2: With description (~200 bytes)
const templates = await searchTemplates(client, 'notification', { maxResults: 10 });

// Level 3: Essentials for planning (~2KB)
const nodeInfo = await getNodeInfo(client, 'n8n-nodes-base.slack', 'essentials');

// Level 4: Full data for implementation (~20KB)
const workflow = await getWorkflow(client, 'workflow-123'); // Full workflow JSON

Setup

Configure your n8n instance via environment variables:

# .env file
N8N_URL=https://n8n.example.com
N8N_API_KEY=n8n_api_xxxxx

Two initialization patterns:

// Pattern 1: Read N8N_URL + N8N_API_KEY from env
const client = createClient();

// Pattern 2: Explicit configuration
const client = createClient({
  url: 'https://n8n.example.com',
  apiKey: 'n8n_api_xxxxx'
});

Token Savings Examples

| Operation | MCP Tokens | Code Tokens | Savings | |-----------|------------|-------------|---------| | Workflow discovery | 150,000 | 2,000 | 98.7% | | Execution viewing (preview) | 130,000 | 1,000 | 99.2% | | Node search (name only) | 45,000 | 500 | 98.9% | | Template search (metadata) | 60,000 | 1,500 | 97.5% | | Average | 96,250 | 1,250 | 98.7% |

Navigation (≤3 steps to any tool)

By Use Case

• Workflow Management: API Reference → CRUD, activate/deactivate
• Execution Monitoring: Smart Features → Preview modes, health metrics
• Bulk Operations: Bulk Ops → Parallel activate/deactivate/export/import
• Discovery: Search → Nodes, templates with fuzzy matching
• Validation: Validation → Multi-layer checking + autofix

By Module

• workflows.ts - CRUD (create, get, list, update, get tags, update tags, execute). Note: activateWorkflow, deactivateWorkflow, transferWorkflow, and deleteWorkflow are now top-level toolkit actions exported directly from n8n-code-toolkit for ease of use.
• executions.ts - List, get, delete, retry, stats
• credentials.ts, tags.ts, variables.ts, users.ts, projects.ts
• audit.ts, source-control.ts

• search-nodes.ts - Fuzzy search with Fuse.js
• search-templates.ts - Template discovery
• get-node-info.ts - Progressive disclosure (4 levels)
• get-template.ts - 3 modes (nodes_only, structure, full)

• validate-workflow.ts - Orchestrator
• validate-node.ts, validate-connections.ts, validate-expressions.ts
• autofix.ts - Automatic error correction with confidence scoring

• smart-execution-viewer.ts - 4 modes (preview/summary/filtered/full)
• smart-workflow-filter.ts - Metadata-only mode (90%+ reduction)

• activate-workflows.ts, deactivate-workflows.ts
• export-workflows.ts, import-workflows.ts (with validation/autofix)

• check-failed-executions.ts - Aggregate by workflow + error type
• workflow-health.ts - Success rate, status (healthy/degraded/unhealthy)
• credential-audit.ts - Usage tracking, unused detection

• instantiate-template.ts - Pure function to build from template with customization (variables, credentials)

• version.ts - Semver parsing and comparison utilities
• matrix.ts - Endpoint requirements + checkCompatibility() report

Version Detection

Detect n8n instance version and check feature compatibility at runtime:

import { createClient, getInstanceInfo, checkCompatibility } from 'n8n-code-toolkit';

const client = createClient();

// Check what version is running
const info = await getInstanceInfo(client);
console.log(info.n8nVersion); // e.g. "1.73.1"

// Get a full compatibility report
const report = await checkCompatibility(client);
if (!report.compatible) {
  console.warn('Unsupported features:', report.warnings);
}

See COMPATIBILITY.md for the version matrix.

Troubleshooting

Issue: "Configuration file not found"

Solution: Ensure .env file exists with N8N_* variables. The toolkit auto-loads environment variables on import.

Issue: API connection refused

Solution: Verify n8n instance is running and URL/port are correct:

curl https://n8n.example.com/api/v1/workflows

Issue: TypeScript errors about missing types

Solution: Ensure you're importing from the main package:

import { createClient, Workflow } from 'n8n-code-toolkit';

Issue: Token savings not as expected

Solution: Use progressive disclosure levels and metadata-only modes:

// ❌ Full data (large)
const workflows = await filterWorkflows(client, { tags: ['prod'] });

// ✅ Metadata only (90%+ smaller)
const workflows = await filterWorkflows(client, {
  tags: ['prod'],
  metadataOnly: true
});

Testing

The toolkit includes a comprehensive QA suite that validates functionality against a live n8n instance.

# Run QA suite (requires .env configuration)
npm run test:qa

See QA_REPORT.md for the latest validation results.

API Limitations & Workarounds

The n8n Public API (v1) has specific constraints handled by this toolkit:

1. Strict PUT Payload: updateWorkflow strictly filters payload to only allowed mutable fields to avoid "additional properties" errors. This toolkit's updateWorkflow now handles this by constructing a whitelist of properties.
2. Activation/Deactivation: activateWorkflow and deactivateWorkflow require specific POST requests with a null body (not an empty object or array). The toolkit's wrappers handle this specific client configuration.
3. Tag Updates: PUT /workflows/{id}/tags expects an array of tag objects (e.g., [{ name: "tag1" }]), not just strings or an object wrapper. The toolkit's updateWorkflowTags handles this transformation.
4. Read-Only Tags on Create: You cannot set tags during workflow creation.
   • Solution: The toolkit's builders create the workflow first, then apply tags via a separate update.
5. List Limits: The API limits list results to 250 items.
   • Solution: filterWorkflows and other list functions handle pagination automatically.
6. Tag Conflicts: Tag creation can be flaky (409 conflicts).
   • Solution: Logic includes fallback to existing tags.
7. Missing Endpoints: Credentials listing and Node Type discovery are not available via the Public API key.
   • Impact: Some monitoring/discovery features run in degraded/fallback mode.

Documentation Links

• API Reference - All 60+ functions with examples
• Migration Guide - MCP to Code mapping
• Setup Guide - Three installation methods
• Examples - Real-world usage scripts

Built for token efficiency | MIT License