Initial commit of n8n MCP Server

A Model Context Protocol (MCP) server that integrates with n8n, providing tools for workflow and execution management via the n8n API.

docs/api/execution-tools.md

@@ -0,0 +1,315 @@
+# Execution Tools
+
+This page documents the tools available for managing n8n workflow executions.
+
+## Overview
+
+Execution tools allow AI assistants to execute n8n workflows and manage execution records. These tools provide a natural language interface to n8n's execution capabilities, allowing workflows to be run, monitored, and their results accessed.
+
+## Available Tools
+
+### execution_run
+
+Executes a workflow with optional input data.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "workflowId": {
+      "type": "string",
+      "description": "ID of the workflow to execute"
+    },
+    "data": {
+      "type": "object",
+      "description": "Input data to pass to the workflow"
+    },
+    "waitForCompletion": {
+      "type": "boolean",
+      "description": "Whether to wait for the workflow to complete before returning",
+      "default": false
+    }
+  },
+  "required": ["workflowId"]
+}
+```
+
+**Example Usage:**
+
+```javascript
+// Execute without waiting
+const execution = await useExecutionRun({
+  workflowId: "1234abc"
+});
+
+// Execute with input data
+const executionWithData = await useExecutionRun({
+  workflowId: "1234abc",
+  data: {
+    firstName: "John",
+    lastName: "Doe",
+    email: "john.doe@example.com"
+  }
+});
+
+// Execute and wait for completion
+const completedExecution = await useExecutionRun({
+  workflowId: "1234abc",
+  waitForCompletion: true
+});
+```
+
+**Response (when waitForCompletion: false):**
+
+```javascript
+{
+  "executionId": "exec789",
+  "status": "running",
+  "startedAt": "2025-03-12T16:30:00.000Z"
+}
+```
+
+**Response (when waitForCompletion: true):**
+
+```javascript
+{
+  "executionId": "exec789",
+  "status": "success", // Or "error" if execution failed
+  "startedAt": "2025-03-12T16:30:00.000Z",
+  "finishedAt": "2025-03-12T16:30:05.000Z",
+  "data": {
+    // Output data from the workflow execution
+  }
+}
+```
+
+### execution_get
+
+Retrieves details of a specific execution.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "executionId": {
+      "type": "string",
+      "description": "ID of the execution to retrieve"
+    }
+  },
+  "required": ["executionId"]
+}
+```
+
+**Example Usage:**
+
+```javascript
+const execution = await useExecutionGet({
+  executionId: "exec789"
+});
+```
+
+**Response:**
+
+```javascript
+{
+  "id": "exec789",
+  "workflowId": "1234abc",
+  "workflowName": "Test Workflow 1",
+  "status": "success", // Or "error", "running", "waiting", etc.
+  "startedAt": "2025-03-12T16:30:00.000Z",
+  "finishedAt": "2025-03-12T16:30:05.000Z",
+  "mode": "manual",
+  "data": {
+    "resultData": {
+      // Output data from the workflow execution
+    },
+    "executionData": {
+      // Detailed execution data including node inputs/outputs
+    },
+    "metadata": {
+      // Execution metadata
+    }
+  }
+}
+```
+
+### execution_list
+
+Lists executions for a specific workflow.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "workflowId": {
+      "type": "string",
+      "description": "ID of the workflow to get executions for"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Maximum number of executions to return",
+      "default": 20
+    },
+    "status": {
+      "type": "string",
+      "description": "Filter by execution status",
+      "enum": ["success", "error", "running", "waiting"]
+    }
+  },
+  "required": ["workflowId"]
+}
+```
+
+**Example Usage:**
+
+```javascript
+// List all executions for a workflow
+const executions = await useExecutionList({
+  workflowId: "1234abc"
+});
+
+// List with limit
+const limitedExecutions = await useExecutionList({
+  workflowId: "1234abc",
+  limit: 5
+});
+
+// List only successful executions
+const successfulExecutions = await useExecutionList({
+  workflowId: "1234abc",
+  status: "success"
+});
+```
+
+**Response:**
+
+```javascript
+[
+  {
+    "id": "exec789",
+    "workflowId": "1234abc",
+    "status": "success",
+    "startedAt": "2025-03-12T16:30:00.000Z",
+    "finishedAt": "2025-03-12T16:30:05.000Z",
+    "mode": "manual"
+  },
+  {
+    "id": "exec456",
+    "workflowId": "1234abc",
+    "status": "error",
+    "startedAt": "2025-03-11T14:20:00.000Z",
+    "finishedAt": "2025-03-11T14:20:10.000Z",
+    "mode": "manual"
+  }
+]
+```
+
+### execution_delete
+
+Deletes an execution record.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "executionId": {
+      "type": "string",
+      "description": "ID of the execution to delete"
+    }
+  },
+  "required": ["executionId"]
+}
+```
+
+**Example Usage:**
+
+```javascript
+await useExecutionDelete({
+  executionId: "exec789"
+});
+```
+
+**Response:**
+
+```javascript
+{
+  "success": true
+}
+```
+
+### execution_stop
+
+Stops a running execution.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "executionId": {
+      "type": "string",
+      "description": "ID of the execution to stop"
+    }
+  },
+  "required": ["executionId"]
+}
+```
+
+**Example Usage:**
+
+```javascript
+await useExecutionStop({
+  executionId: "exec789"
+});
+```
+
+**Response:**
+
+```javascript
+{
+  "success": true,
+  "status": "cancelled",
+  "stoppedAt": "2025-03-12T16:32:00.000Z"
+}
+```
+
+## Execution Status Codes
+
+Executions can have the following status codes:
+
+| Status | Description |
+|--------|-------------|
+| `running` | The execution is currently in progress |
+| `success` | The execution completed successfully |
+| `error` | The execution failed with an error |
+| `waiting` | The execution is waiting for a webhook or other event |
+| `cancelled` | The execution was manually stopped |
+
+## Error Handling
+
+All execution tools can return the following errors:
+
+| Error | Description |
+|-------|-------------|
+| Authentication Error | The provided API key is invalid or missing |
+| Not Found Error | The requested workflow or execution does not exist |
+| Validation Error | The input parameters are invalid or incomplete |
+| Permission Error | The API key does not have permission to perform the operation |
+| Server Error | An unexpected error occurred on the n8n server |
+
+## Best Practices
+
+- Check if a workflow is active before attempting to execute it
+- Use `waitForCompletion: true` for short-running workflows, but be cautious with long-running workflows
+- Always handle potential errors when executing workflows
+- Filter executions by status to find problematic runs
+- Use execution IDs from `execution_run` responses to track workflow progress