@thecodesaiyan/tcs-n8n-mcp 1.0.3 → 1.0.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Nigel Tatschner
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Nigel Tatschner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,72 @@
+<div align="center">
+
 # @thecodesaiyan/tcs-n8n-mcp
 
-By [@TheCodeSaiyan](https://github.com/ntatschner)
+**Manage your n8n workflows through AI assistants**
+
+[![npm version](https://img.shields.io/npm/v/@thecodesaiyan/tcs-n8n-mcp?color=blue&label=npm)](https://www.npmjs.com/package/@thecodesaiyan/tcs-n8n-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io)
+[![CI](https://github.com/ntatschner/tcs-n8n-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ntatschner/tcs-n8n-mcp/actions/workflows/ci.yml)
+
+An [MCP](https://modelcontextprotocol.io) server that gives AI assistants full control over your [n8n](https://n8n.io) workflow automation platform. List, create, update, execute, and manage workflows, executions, tags, variables, credentials, and users — all through natural language.
+
+[Installation](#installation) · [Tools](#available-tools-22) · [Security](#security) · [Development](#development)
+
+</div>
+
+---
+
+## Features
+
+- **22 tools** covering the full n8n REST API
+- **Works everywhere** — Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, Cline
+- **Secure by default** — ID validation, sanitised errors, masked secrets, request timeouts
+- **Zero config** — just provide your n8n API key and go
+- **Lightweight** — under 30KB, no runtime dependencies beyond the MCP SDK and Zod
+
+---
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) >= 18
+- An [n8n](https://n8n.io) instance (self-hosted or cloud)
+- An n8n API key ([how to create one](https://docs.n8n.io/api/authentication/))
 
-An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for managing [n8n](https://n8n.io) workflow automation instances. Provides 22 tools for workflows, executions, tags, variables, credentials, and users.
+---
 
 ## Installation
 
-### Claude Code
+### Quick Start
 
-Run the CLI command:
+```bash
+npx @thecodesaiyan/tcs-n8n-mcp
+```
+
+Set the required environment variables:
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `N8N_API_KEY` | Yes | — | Your n8n API key |
+| `N8N_API_URL` | No | `http://localhost:5678` | Base URL of your n8n instance |
+
+---
+
+### Client Setup
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+#### Option A: CLI command
 
 ```bash
 claude mcp add n8n -- npx -y @thecodesaiyan/tcs-n8n-mcp
 ```
 
-Or add to `~/.claude.json`:
+#### Option B: Manual config
+
+Add to `~/.claude.json`:
 
 ```json
 {
@@ -31,12 +83,18 @@ Or add to `~/.claude.json`:
 }
 ```
 
-### Claude Desktop
+</details>
 
-Add to your config file:
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to your Claude Desktop config file:
+
+| OS | Path |
+|----|------|
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
 
 ```json
 {
@@ -53,11 +111,14 @@ Add to your config file:
 }
 ```
 
-Restart Claude Desktop after saving.
+> Restart Claude Desktop after saving.
+
+</details>
 
-### VS Code (Copilot)
+<details>
+<summary><strong>VS Code (GitHub Copilot)</strong></summary>
 
-Add to `.vscode/mcp.json` in your project, or open user config via Command Palette > `MCP: Open User Configuration`:
+Add to `.vscode/mcp.json` in your project, or use **Command Palette** > `MCP: Open User Configuration`:
 
 ```json
 {
@@ -74,9 +135,12 @@ Add to `.vscode/mcp.json` in your project, or open user config via Command Palet
 }
 ```
 
-### Cursor
+</details>
 
-Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-level):
 
 ```json
 {
@@ -93,11 +157,17 @@ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
 }
 ```
 
-### Windsurf
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to your Windsurf config file:
 
-Add to your config file:
-- **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
-- **macOS/Linux**: `~/.codeium/windsurf/mcp_config.json`
+| OS | Path |
+|----|------|
+| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
+| macOS / Linux | `~/.codeium/windsurf/mcp_config.json` |
 
 ```json
 {
@@ -114,9 +184,12 @@ Add to your config file:
 }
 ```
 
-### Cline
+</details>
 
-Open MCP Servers > Configure > Advanced MCP Settings, and add:
+<details>
+<summary><strong>Cline</strong></summary>
+
+Open **MCP Servers** > **Configure** > **Advanced MCP Settings** and add:
 
 ```json
 {
@@ -133,77 +206,80 @@ Open MCP Servers > Configure > Advanced MCP Settings, and add:
 }
 ```
 
-> **Windows note**: If you encounter spawn errors with npx, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@thecodesaiyan/tcs-n8n-mcp"]` instead.
+> **Windows**: If you encounter spawn errors, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@thecodesaiyan/tcs-n8n-mcp"]`.
 
-## Environment Variables
+</details>
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `N8N_API_KEY` | Yes | — | n8n API key ([how to create](https://docs.n8n.io/api/authentication/)) |
-| `N8N_API_URL` | No | `http://localhost:5678` | Base URL of your n8n instance |
+---
 
 ## Available Tools (22)
 
 ### Workflows (8)
 
 | Tool | Description |
-|------|-------------|
+|:-----|:------------|
 | `list_workflows` | List all workflows with pagination |
-| `get_workflow` | Get full workflow details by ID |
-| `create_workflow` | Create a new workflow |
-| `update_workflow` | Update an existing workflow |
-| `delete_workflow` | Delete a workflow (irreversible) |
-| `activate_workflow` | Activate a workflow's triggers |
-| `deactivate_workflow` | Deactivate a workflow |
-| `execute_workflow` | Execute a workflow immediately |
+| `get_workflow` | Get full workflow details including nodes, connections, and settings |
+| `create_workflow` | Create a new workflow with optional nodes and connections |
+| `update_workflow` | Update an existing workflow's name, nodes, connections, or settings |
+| `delete_workflow` | Permanently delete a workflow |
+| `activate_workflow` | Activate a workflow so it runs on its configured triggers |
+| `deactivate_workflow` | Deactivate a workflow to stop trigger-based execution |
+| `execute_workflow` | Execute a workflow immediately and return the execution ID |
 
 ### Executions (3)
 
 | Tool | Description |
-|------|-------------|
-| `list_executions` | List executions with filters |
-| `get_execution` | Get execution details and results |
+|:-----|:------------|
+| `list_executions` | List executions with optional filters for workflow ID and status |
+| `get_execution` | Get full execution details including per-node results and errors |
 | `delete_execution` | Delete an execution record |
 
 ### Tags (4)
 
 | Tool | Description |
-|------|-------------|
-| `list_tags` | List all tags |
+|:-----|:------------|
+| `list_tags` | List all tags used for organising workflows |
 | `create_tag` | Create a new tag |
-| `update_tag` | Rename a tag |
+| `update_tag` | Rename an existing tag |
 | `delete_tag` | Delete a tag |
 
 ### Variables (4)
 
 | Tool | Description |
-|------|-------------|
-| `list_variables` | List all variables (values masked) |
-| `create_variable` | Create a new variable |
-| `update_variable` | Update a variable |
-| `delete_variable` | Delete a variable |
+|:-----|:------------|
+| `list_variables` | List all environment variables (values are masked for security) |
+| `create_variable` | Create a new key-value environment variable |
+| `update_variable` | Update an existing variable's key or value |
+| `delete_variable` | Delete an environment variable |
 
 ### Credentials (1)
 
 | Tool | Description |
-|------|-------------|
-| `list_credentials` | List credentials (metadata only) |
+|:-----|:------------|
+| `list_credentials` | List all credentials (metadata only — secrets are never exposed) |
 
 ### Users (2)
 
 | Tool | Description |
-|------|-------------|
-| `list_users` | List all users |
-| `get_user` | Get user details |
+|:-----|:------------|
+| `list_users` | List all users with their roles and status |
+| `get_user` | Get full details of a user by ID |
+
+---
 
 ## Security
 
-- All resource IDs are validated as numeric strings to prevent path traversal
-- Error responses are sanitised to avoid leaking n8n instance internals
-- Variable values are masked in list output to prevent secret exposure
-- All API calls have a 30-second timeout
-- API keys are never logged or exposed in tool output
-- Credentials tool only returns metadata (secrets are never exposed)
+| Protection | Description |
+|:-----------|:------------|
+| **ID Validation** | All resource IDs are validated as numeric strings to prevent path traversal attacks |
+| **Error Sanitisation** | API error responses only return HTTP status codes, never raw response bodies |
+| **Secret Masking** | Variable values are hidden in list output to prevent accidental secret exposure |
+| **Request Timeout** | All API calls have a 30-second timeout to prevent hanging connections |
+| **No Key Logging** | API keys are never logged, echoed, or included in tool output |
+| **Credential Safety** | The credentials tool only returns metadata — secrets are never exposed |
+
+---
 
 ## Development
 
@@ -211,16 +287,54 @@ Open MCP Servers > Configure > Advanced MCP Settings, and add:
 git clone https://github.com/ntatschner/tcs-n8n-mcp.git
 cd tcs-n8n-mcp
 npm install
-npm run build
-npm test
 ```
 
+### Commands
+
+| Command | Description |
+|:--------|:------------|
+| `npm run build` | Compile TypeScript to `build/` |
+| `npm test` | Run test suite |
+| `npm run test:coverage` | Run tests with coverage report |
+| `npm start` | Start the MCP server |
+
 ### Running locally
 
 ```bash
 N8N_API_KEY=your-key N8N_API_URL=http://localhost:5678 npm start
 ```
 
+### Project Structure
+
+```
+src/
+  index.ts              Entry point, fetch wrapper, server setup
+  types.ts              Shared types, interfaces, response helpers
+  validation.ts         Zod schemas for input validation
+  tools/
+    workflows.ts        Workflow CRUD, activation, execution
+    executions.ts       Execution listing and management
+    tags.ts             Tag CRUD operations
+    variables.ts        Environment variable management
+    credentials.ts      Credential metadata listing
+    users.ts            User listing and details
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feat/my-feature`)
+3. Run tests (`npm test`)
+4. Commit your changes (`git commit -m 'feat: add my feature'`)
+5. Push to the branch (`git push origin feat/my-feature`)
+6. Open a Pull Request
+
+---
+
 ## License
 
-MIT
+[MIT](LICENSE) — Made by [@ntatschner](https://github.com/ntatschner)

package/build/index.js

@@ -30,7 +30,7 @@ const n8nFetch = (path, options = {}) => {
 };
 const server = new McpServer({
     name: "@thecodesaiyan/tcs-n8n-mcp",
-    version: "1.0.3",
+    version: "1.0.6",
 });
 // Register all tool modules
 registerWorkflowTools(server, n8nFetch);
@@ -42,7 +42,7 @@ registerUserTools(server, n8nFetch);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("@thecodesaiyan/tcs-n8n-mcp v1.0.3 running on stdio (22 tools)");
+    console.error("@thecodesaiyan/tcs-n8n-mcp v1.0.6 running on stdio (22 tools)");
 }
 main().catch((error) => {
     console.error("Fatal error:", error);

package/build/tools/workflows.js

@@ -7,9 +7,9 @@ const nodeSchema = z.object({
     type: z.string(),
     typeVersion: z.number(),
     position: z.tuple([z.number(), z.number()]),
-    parameters: z.record(z.unknown()).optional().default({}),
+    parameters: z.record(z.string(), z.unknown()).optional().default({}),
     onError: z.string().optional().describe("Error handling: 'continueRegularOutput' | 'continueErrorOutput' | 'stopWorkflow'"),
-    credentials: z.record(z.unknown()).optional().describe("Credential references for this node"),
+    credentials: z.record(z.string(), z.unknown()).optional().describe("Credential references for this node"),
     webhookId: z.string().optional().describe("Webhook ID for trigger nodes"),
 });
 export function registerWorkflowTools(server, n8nFetch) {
@@ -50,8 +50,8 @@ export function registerWorkflowTools(server, n8nFetch) {
     server.tool("create_workflow", "Create a new n8n workflow. Provide a name and optionally nodes/connections. Defaults to a Manual Trigger node if no nodes given.", {
         name: z.string().describe("Workflow name"),
         nodes: z.array(nodeSchema).optional().describe("Array of workflow nodes (defaults to Manual Trigger)"),
-        connections: z.record(z.unknown()).optional().default({}).describe("Node connections mapping"),
-        settings: z.record(z.unknown()).optional().default({}).describe("Workflow settings"),
+        connections: z.record(z.string(), z.unknown()).optional().default({}).describe("Node connections mapping"),
+        settings: z.record(z.string(), z.unknown()).optional().default({}).describe("Workflow settings"),
     }, async ({ name, nodes, connections, settings }) => {
         const defaultNodes = [
             {
@@ -77,8 +77,8 @@ export function registerWorkflowTools(server, n8nFetch) {
         workflowId: n8nId.describe("ID of the workflow to update"),
         name: z.string().optional().describe("New workflow name"),
         nodes: z.array(nodeSchema).optional().describe("Updated nodes array"),
-        connections: z.record(z.unknown()).optional().describe("Updated connections"),
-        settings: z.record(z.unknown()).optional().describe("Updated settings"),
+        connections: z.record(z.string(), z.unknown()).optional().describe("Updated connections"),
+        settings: z.record(z.string(), z.unknown()).optional().describe("Updated settings"),
     }, async ({ workflowId, name, nodes, connections, settings }) => {
         const getRes = await n8nFetch(`/workflows/${workflowId}`);
         if (!getRes.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecodesaiyan/tcs-n8n-mcp",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "MCP server for n8n workflow automation. Manage workflows, executions, tags, variables, credentials and users via the Model Context Protocol.",
   "type": "module",
   "main": "build/index.js",
@@ -46,7 +46,7 @@
   "homepage": "https://github.com/ntatschner/tcs-n8n-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "zod": "^3.23.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",