API Architecture Overview¶

// Workflow Tools (8 operations)
const workflowTools = [
  'list_workflows',      // List with filtering & pagination
  'get_workflow',        // Retrieve complete workflow
  'create_workflow',     // Create new workflow
  'update_workflow',     // Modify existing workflow
  'delete_workflow',     // Permanently remove workflow
  'activate_workflow',   // Enable workflow execution
  'deactivate_workflow', // Disable workflow execution
  'execute_workflow'     // Manual execution (limited)
];

// Execution Tools (4 operations)
const executionTools = [
  'list_executions',  // List execution history
  'get_execution',    // Get detailed execution data
  'delete_execution', // Remove execution records
  'retry_execution'   // Retry failed executions
];

// Credential Tools (6 operations)
const credentialTools = [
  'list_credentials',      // Security guidance (blocked by n8n)
  'get_credential',        // Security guidance (blocked by n8n)
  'create_credential',     // Schema-driven creation
  'update_credential',     // Immutability guidance
  'delete_credential',     // Permanent removal
  'get_credential_schema'  // Get JSON schema
];

// Tag Tools (5 operations)
const tagTools = [
  'create_tag',  // Create workflow tags
  'get_tags',    // List all tags
  'get_tag',     // Get specific tag
  'update_tag',  // Rename tag
  'delete_tag'   // Remove tag
];

class EnvironmentManager {
  private static instance: EnvironmentManager;
  private apiInstances: Map<string, N8NApiWrapper>;
  private config: MultiInstanceConfig;

  // Singleton access
  public static getInstance(): EnvironmentManager;

  // Get or create API wrapper for environment
  public getApi(instanceName?: string): N8NApiWrapper;

  // List available environments
  public listEnvironments(): string[];

  // Get default environment name
  public getDefaultEnvironment(): string;

  // Validate environment exists
  public validateEnvironment(name: string): void;

  // Clear cached API instances
  public clearCache(instanceName?: string): void;
}

class N8NApiWrapper {
  private baseURL: string;        // e.g., https://n8n.cloud/api/v1
  private apiKey: string;          // X-N8N-API-KEY header value
  private axiosInstance: AxiosInstance;

  // Workflow operations (8 methods)
  async listWorkflows(params: ListWorkflowsParams): Promise<WorkflowListResponse>;
  async getWorkflow(id: string): Promise<WorkflowDefinition>;
  async createWorkflow(data: CreateWorkflowParams): Promise<WorkflowDefinition>;
  async updateWorkflow(id: string, data: UpdateWorkflowParams): Promise<WorkflowDefinition>;
  async deleteWorkflow(id: string): Promise<void>;
  async activateWorkflow(id: string): Promise<WorkflowDefinition>;
  async deactivateWorkflow(id: string): Promise<WorkflowDefinition>;

  // Execution operations (4 methods)
  async listExecutions(params: ListExecutionsParams): Promise<ExecutionListResponse>;
  async getExecution(id: number, includeData?: boolean): Promise<Execution>;
  async deleteExecution(id: number): Promise<void>;
  async retryExecution(id: number): Promise<Execution>;

  // Credential operations (3 methods)
  async getCredentialSchema(type: string): Promise<CredentialSchema>;
  async createCredential(data: CreateCredentialParams): Promise<Credential>;
  async deleteCredential(id: string): Promise<void>;

  // Tag operations (5 methods)
  async createTag(data: CreateTagParams): Promise<Tag>;
  async getTags(params?: GetTagsParams): Promise<TagListResponse>;
  async getTag(id: string): Promise<Tag>;
  async updateTag(id: string, data: UpdateTagParams): Promise<Tag>;
  async deleteTag(id: string): Promise<void>;
}

{
  baseURL: "https://n8n.example.com/api/v1",
  headers: {
    "X-N8N-API-KEY": "n8n_api_...",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  timeout: 30000,  // 30 seconds
  maxRedirects: 5,
  validateStatus: (status) => status < 500  // Don't throw on 4xx
}

// Input: https://n8n.cloud/api/v1/
// Output: https://n8n.cloud/api/v1

// Server automatically appends /api/v1 during API calls

// list_workflows returns streamlined metadata
{
  id: "123",
  name: "Email Campaign",
  active: true,
  nodes: 15,  // Count only, not full node definitions
  tags: [...],
  createdAt: "...",
  updatedAt: "..."
}

// 90%+ data reduction compared to full workflow objects
// Prevents Claude Desktop crashes with large workflow lists

// First page
const page1 = await list({ limit: 100 });
// Returns: { data: [...], nextCursor: "eyJ..." }

// Second page
const page2 = await list({ limit: 100, cursor: page1.nextCursor });
// Stable pagination even if data changes

// List executions without data (fast)
const executions = await listExecutions({
  workflowId: "123",
  includeData: false  // Metadata only
});

// Get specific execution with full data (slower but detailed)
const execution = await getExecution({
  id: 9876,
  includeData: true  // Full execution data for debugging
});

// Configuration Errors
class ConfigurationError extends Error {
  code: 'CONFIGURATION_ERROR';
  message: 'Missing required configuration: n8n_api_key';
  // Thrown during server startup
}

// Authentication Errors
class AuthenticationError extends Error {
  code: 'AUTHENTICATION_ERROR';
  httpStatus: 401;
  message: 'Invalid API key for instance "production"';
  // Invalid or expired API key
}

// Instance Resolution Errors
class InstanceError extends Error {
  code: 'INSTANCE_NOT_FOUND';
  availableInstances: string[];
  message: 'Instance "prod" not found. Available: production, staging, development';
  // Requested instance doesn't exist in config
}

// n8n API Errors
class ApiError extends Error {
  code: 'API_ERROR';
  httpStatus: number;
  apiResponse: any;
  message: 'Workflow validation failed: missing trigger node';
  // n8n API returned error response
}

// Network Errors
class NetworkError extends Error {
  code: 'NETWORK_ERROR' | 'TIMEOUT' | 'ECONNREFUSED';
  message: 'Connection timeout after 30000ms';
  // Network connectivity issues
}

try {
  const api = envManager.getApi(instanceName);
} catch (error) {
  if (error.code === 'INSTANCE_NOT_FOUND') {
    const available = envManager.listEnvironments();
    throw new Error(
      `Instance "${instanceName}" not found. ` +
      `Available instances: ${available.join(', ')}`
    );
  }
}

async activateWorkflow(id: string): Promise<Workflow> {
  const workflow = await this.getWorkflow(id);

  // Check if workflow has valid trigger
  const hasTrigger = workflow.nodes.some(node =>
    node.type === 'n8n-nodes-base.scheduleTrigger' ||
    node.type === 'n8n-nodes-base.webhook'
  );

  if (!hasTrigger) {
    // Add schedule trigger automatically
    workflow.nodes.push({
      name: 'Schedule Trigger',
      type: 'n8n-nodes-base.scheduleTrigger',
      // ... trigger configuration
    });

    await this.updateWorkflow(id, workflow);
  }

  // Now activate
  return await this.activateWorkflow(id);
}

// ❌ Blocked by n8n API
list_credentials()  // Returns security guidance, not credentials

// ❌ Blocked by n8n API
get_credential(id)  // Returns security guidance, not credential data

// ✅ Allowed: Schema-driven creation
get_credential_schema(type)  // Returns JSON schema
create_credential({ name, type, data })  // Creates encrypted credential

// ✅ Allowed: Reference by ID
workflow.nodes.push({
  credentials: {
    httpBasicAuth: {
      id: "cred_123",  // Reference only, no credential data
      name: "API Credentials"
    }
  }
});