n8n-mcp copilot-instructions.md

n8n-mcp: MCP Server for n8n Workflow Management

An MCP (Model Context Protocol) server for managing n8n workflows. This TypeScript Node.js project provides both a stdio MCP server and CLI interface for creating, retrieving, updating, and managing n8n workflows through the n8n API.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Bootstrap, Build, and Test

CRITICAL: All commands have been validated and measured. Set appropriate timeouts and NEVER CANCEL builds or tests.

# Install dependencies - takes ~11 seconds
npm install

# Lint TypeScript code - takes ~2 seconds  
npm run lint

# Build TypeScript to JavaScript - takes ~2 seconds
npm run build

# Run full test suite - takes ~6 seconds
npm test

# Run tests with coverage - takes ~9 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
npm run test:coverage

TIMEOUT REQUIREMENTS:

• npm install: 60+ seconds (network dependent)
• npm run build: 30 seconds
• npm run test: 30 seconds
• npm run test:coverage: 60 seconds
• NEVER CANCEL any build or test command - wait for completion

Development Workflow

# Start development watch mode (rebuilds on file changes)
npm run dev

# Start the MCP server (requires environment variables)
npm start

# Use CLI interface for testing
npm run cli [command]

Environment Configuration

The application requires n8n instance configuration via environment variables:

# Option 1: API Key Authentication (recommended)
export N8N_BASE_URL=http://localhost:5678
export N8N_API_KEY=your_api_key_here

# Option 2: Basic Authentication
export N8N_BASE_URL=http://localhost:5678
export N8N_USERNAME=your_username
export N8N_PASSWORD=your_password

Validation Scenarios

Manual Validation Requirements

ALWAYS perform these validation steps after making changes:

1. Build Validation: Run npm run build and verify no TypeScript errors
2. Test Validation: Run npm test and verify all 29 tests pass
3. CLI Functionality: Test npm run cli shows help menu correctly
4. Server Startup: Verify server starts with appropriate environment variables
5. Lint Validation: Run npm run lint before committing (CI requirement)