n8n MCP Server

# Architecture This document describes the architectural design of the n8n MCP Server. ## Overview The n8n MCP Server follows a layered architecture pattern that separates concerns and promotes maintainability. The main architectural layers are: 1. **Transport Layer**: Handles communication with AI assistants via the Model Context Protocol 2. **API Client Layer**: Interacts with the n8n API 3. **Tools Layer**: Implements executable operations as MCP tools 4. **Resources Layer**: Provides data access through URI-based resources 5. **Configuration Layer**: Manages environment variables and server settings 6. **Error Handling Layer**: Provides consistent error management and reporting ## System Components  ### Entry Point The server entry point is defined in `src/index.ts`. This file: 1. Initializes the configuration from environment variables 2. Creates and configures the MCP server instance 3. Registers tool and resource handlers 4. Connects to the transport layer (typically stdio) ### Configuration The configuration layer (`src/config/`) handles: - Loading environment variables - Validating required configuration - Providing typed access to configuration values The main configuration component is the `Environment` class, which validates and manages environment variables like `N8N_API_URL` and `N8N_API_KEY`. ### API Client The API client layer (`src/api/`) provides a clean interface for interacting with the n8n API. It includes: - `N8nClient`: The main client that encapsulates communication with n8n - API-specific functionality divided by resource type (workflows, executions) - Authentication handling using the n8n API key The client uses Axios for HTTP requests and includes error handling specific to the n8n API responses. ### MCP Tools The tools layer (`src/tools/`) implements the executable operations exposed to AI assistants. Each tool follows a common pattern: 1. A tool definition that specifies name, description, and input schema 2. A handler function that processes input parameters and executes the operation 3. Error handling for validation and execution errors Tools are categorized by resource type: - Workflow tools: Create, list, update, delete, activate, and deactivate workflows - Execution tools: Run, list, and manage workflow executions Each tool is designed to be independently testable and maintains a clean separation of concerns. ### MCP Resources The resources layer (`src/resources/`) provides data access through URI-based templates. Resources are divided into two categories: 1. **Static Resources** (`src/resources/static/`): Fixed resources like workflow listings 2. **Dynamic Resources** (`src/resources/dynamic/`): Parameterized resources like specific workflow details Each resource implements: - URI pattern matching - Content retrieval - Error handling - Response formatting ### Error Handling The error handling layer (`src/errors/`) provides consistent error management across the server. It includes: - Custom error types that map to MCP error codes - Error translation functions to convert n8n API errors to MCP errors - Common error patterns and handling strategies ## Data Flow A typical data flow through the system: 1. AI assistant sends a request via stdin to the MCP server 2. Server routes the request to the appropriate handler based on the request type 3. Handler validates input and delegates to the appropriate tool or resource 4. Tool/resource uses the n8n API client to interact with n8n 5. Response is processed, formatted, and returned via stdout 6. AI assistant receives and processes the response ## Key Design Principles ### 1. Separation of Concerns Each component has a single responsibility, making the codebase easier to understand, test, and extend. ### 2. Type Safety TypeScript interfaces and types are used extensively to ensure type safety and provide better developer experience. ### 3. Error Handling Comprehensive error handling ensures that errors are caught at the appropriate level and translated into meaningful messages for AI assistants. ### 4. Testability The architecture supports unit testing by keeping components loosely coupled and maintaining clear boundaries between layers. ### 5. Extensibility New tools and resources can be added without modifying existing code, following the open-closed principle. ## Implementation Patterns ### Factory Pattern Used for creating client instances and tool handlers based on configuration. ### Adapter Pattern The n8n API client adapts the n8n API to the internal representation used by the server. ### Strategy Pattern Different resource handlers implement a common interface but provide different strategies for retrieving and formatting data. ### Decorator Pattern Used to add cross-cutting concerns like logging and error handling to base functionality. ## Core Files and Their Purposes | File | Purpose | |------|---------| | `src/index.ts` | Main entry point, initializes and configures the server | | `src/config/environment.ts` | Manages environment variables and configuration | | `src/api/n8n-client.ts` | Main client for interacting with the n8n API | | `src/tools/workflow/handler.ts` | Handles workflow-related tool requests | | `src/tools/execution/handler.ts` | Handles execution-related tool requests | | `src/resources/index.ts` | Registers and manages resource handlers | | `src/resources/dynamic/workflow.ts` | Provides access to specific workflow resources | | `src/resources/static/workflows.ts` | Provides access to workflow listings | | `src/errors/index.ts` | Defines and manages error types and handling | ## Extension Points To extend the server with new capabilities: 1. **Adding a new tool**: Create a new handler in the appropriate category under `src/tools/` and register it in the main server setup 2. **Adding a new resource**: Create a new resource handler in `src/resources/` and register it in the resource manager 3. **Supporting new n8n API features**: Extend the API client in `src/api/` to support new API endpoints or features For detailed instructions on extending the server, see [Extending the Server](./extending.md).