@path58/n8n-mcp 0.1.0

package/AGENT_INSTALL.md

@@ -0,0 +1,223 @@
+# P58-n8n — Drop & Install
+
+**For users:** Drop this file into any AI chat and say: **"Install this MCP server for me"**
+
+**For AI agents:** Follow the instructions in the AI AGENT section below.
+
+---
+
+## What you'll get
+
+P58-n8n gives your AI assistant deep n8n workflow knowledge — 1,982 nodes, 40,179 operations, 26 auto-fix rules.
+
+| Tool | What it does |
+|------|-------------|
+| `validate_workflow` | Run L1-L6 validation on workflow JSON |
+| `get_operation_schema` | Get exact parameter requirements for any operation |
+| `check_parameter` | Validate a parameter value with typo detection |
+| `suggest_fix` | Get fix suggestions for validation issues |
+| `list_nodes` | Browse and search 1,982 n8n nodes |
+| `list_operations` | List all operations for a node type |
+| `get_node_info` | Get comprehensive node metadata |
+| `find_similar_pattern` | Search 9,000+ validated workflows |
+
+### Supported clients
+
+| Client | Support | Transport |
+|--------|---------|-----------|
+| Claude Desktop (Chat + Cowork) | Primary | stdio |
+| Claude Code (CLI) | Primary | stdio |
+| Gemini CLI | Secondary | stdio |
+| ChatGPT Desktop | Not supported | Requires HTTP/SSE |
+
+---
+
+## AI AGENT: Follow These Instructions
+
+### STEP 1 — Detect Environment
+
+Determine your capabilities and the user's platform.
+
+**Can you execute commands?**
+```
+Can I run shell commands?
+├─ YES (Claude Code, Cowork mode, Gemini CLI)  → Go to STEP 2a (Auto-Install)
+└─ NO  (Claude Desktop Chat-only)              → Go to STEP 2b (Guided Install)
+```
+
+**Detect platform:**
+```
+What OS is the user on?
+├─ macOS    → Config paths use ~/Library/Application Support/
+├─ Windows  → Config paths use %APPDATA%\
+└─ Linux    → Config paths use ~/.config/
+```
+
+---
+
+### STEP 2a — Auto-Install (can run commands)
+
+**Prerequisites — verify first:**
+
+```bash
+node --version
+# Must be v18.0.0 or higher. If not installed, tell the user to install from https://nodejs.org/
+```
+
+**Then install based on which client the user wants:**
+
+#### Claude Code
+
+Run this single command:
+
+```bash
+claude mcp add p58-n8n -- npx -y @path58/n8n-mcp
+```
+
+Done. Skip to STEP 3.
+
+#### Claude Desktop (Cowork mode — can write files)
+
+Read the existing config file first, then MERGE the p58-n8n entry. NEVER overwrite the entire file.
+
+**Config file paths:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+**If file exists:** Read it, parse the JSON, add this entry inside `mcpServers`:
+
+```json
+"p58-n8n": {
+  "command": "npx",
+  "args": ["-y", "@path58/n8n-mcp"]
+}
+```
+
+**If file doesn't exist:** Create it with:
+
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "npx",
+      "args": ["-y", "@path58/n8n-mcp"]
+    }
+  }
+}
+```
+
+Tell the user to restart Claude Desktop.
+
+#### Gemini CLI
+
+There is NO `gemini mcp add` command. Edit the config file directly.
+
+**Config path:** `~/.gemini/settings.json` (user-level) or `.gemini/settings.json` (project-level)
+
+**If file exists:** Read it, parse JSON, add the `p58-n8n` entry inside `mcpServers`.
+
+**If file doesn't exist:** Create it with:
+
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "npx",
+      "args": ["-y", "@path58/n8n-mcp"]
+    }
+  }
+}
+```
+
+---
+
+### STEP 2b — Guided Install (chat-only)
+
+Ask the user which client they want to set up, then give them copy-paste instructions.
+
+**Ask:** "Which AI client do you want to use P58-n8n with?"
+
+#### For Claude Desktop
+
+Tell the user:
+
+1. Open your Claude Desktop config file:
+   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+   - **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+2. Add this inside the `mcpServers` object (create the file if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "npx",
+      "args": ["-y", "@path58/n8n-mcp"]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop.
+
+#### For Claude Code
+
+Tell the user to run:
+
+```bash
+claude mcp add p58-n8n -- npx -y @path58/n8n-mcp
+```
+
+#### For Gemini CLI
+
+Tell the user:
+
+1. Open `~/.gemini/settings.json` (create if needed)
+2. Add:
+
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "npx",
+      "args": ["-y", "@path58/n8n-mcp"]
+    }
+  }
+}
+```
+
+#### For ChatGPT Desktop
+
+Tell the user: **ChatGPT Desktop is not supported.** It requires HTTP/SSE transport for MCP servers, but P58-n8n uses stdio transport. This may be supported in a future version.
+
+---
+
+### STEP 3 — Verify Installation
+
+After setup, test with this prompt:
+
+> "List available n8n nodes for email"
+
+**Expected result:** The AI calls `list_nodes` and returns nodes like `n8n-nodes-base.gmail`, `n8n-nodes-base.emailSend`, etc.
+
+**If it doesn't work:**
+
+```
+Tools not appearing?
+├─ Config file in wrong location   → Check OS-specific paths above
+├─ Invalid JSON syntax             → Validate with: cat <path> | python3 -m json.tool
+├─ Client not restarted            → Close and reopen the AI client
+├─ npx not found                   → Install Node.js 18+ from https://nodejs.org/
+└─ Permission error                → Try: sudo npm install -g @path58/n8n-mcp
+
+Server starts but tools don't work?
+├─ Database not accessible         → Server needs network access to Supabase
+├─ Timeout errors                  → Check internet connection
+└─ "Module not found"              → Run: npm install -g @path58/n8n-mcp (reinstall)
+```
+
+---
+
+**Package:** `@path58/n8n-mcp` | **License:** MIT | **Built by [Path58](https://path58.com)**

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-06
+
+### Added
+
+- **MCP Server** with 8 tools for LLM integration via stdio transport
+  - `validate_workflow` — Full L1-L6 static validation pipeline
+  - `get_operation_schema` — Parameter requirements lookup for any node operation
+  - `check_parameter` — Real-time parameter validation against catalog
+  - `suggest_fix` — Concrete fix suggestions powered by 26 deterministic auto-fixers
+  - `list_operations` — Browse all operations for a given node type
+  - `list_nodes` — Search and browse 1,982 available n8n nodes
+  - `get_node_info` — Full node details, configuration, and metadata
+  - `find_similar_pattern` — Working examples from 9,178 real workflows
+- **L1-L6 Static Validation Pipeline** (~1.4s total)
+  - L1: JSON structure, required fields, duplicate detection (~30ms)
+  - L2: Node type catalog validation (~60ms)
+  - L3: Credential type validation (~80ms)
+  - L4: Connection topology validation (~180ms)
+  - L5: Parameter configuration validation (~850ms)
+  - L6: Flow integrity, security, and expression patterns (~200ms)
+- **AutoFix Infrastructure** with 26 deterministic fixers across L1-L6
+  - Zero LLM cost for automatic repairs
+  - 97%+ success rate on fixable errors
+- **Node Catalog** with 1,982 nodes, 654 credential types, 40,179 operations
+- **Pattern Library** with 9,178 real workflow patterns for discovery
+- **Multi-client support** for Claude Desktop, Claude Code, and Gemini CLI
+- **Drop-and-install** configuration via `AGENT_INSTALL.md`
+- npm package published as `@path58/n8n-mcp`
+- ESM module support with shebang for direct `npx` execution
+
+[0.1.0]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Path58
+
+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

@@ -0,0 +1,187 @@
+# P58-n8n — Path58's n8n MCP Server
+
+**Enterprise-grade n8n workflow validation for LLMs**
+
+[![npm](https://img.shields.io/npm/v/@path58/n8n-mcp)](https://www.npmjs.com/package/@path58/n8n-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+P58-n8n gives your AI assistant deep knowledge of n8n — **1,982 nodes**, **40,179 operations**, and **26 auto-fix rules** — so it can build, validate, and fix workflows correctly the first time.
+
+---
+
+## Why P58-n8n?
+
+| Metric | P58-n8n | n8n-mcp | Claude alone |
+|--------|---------|---------|-------------|
+| **Accuracy** | 63.6% | 59.1% | 42.0% |
+| **Cost per prompt** | $0.25 | $0.76 | ~$0.05 |
+| **Reliability** | 100% | 82% | 100% |
+| **Token usage** | 1x | 3.2x | 0.3x |
+
+> 4.5 percentage points more accurate, 67% cheaper, and 100% reliable.
+> Benchmarked on 22 real-world workflow generation tasks.
+
+---
+
+## Quick Start (< 5 minutes)
+
+### 1. Configure your AI client
+
+**Claude Code** (one command):
+
+```bash
+claude mcp add p58-n8n -- npx -y @path58/n8n-mcp
+```
+
+**Claude Desktop:**
+
+Add to your `claude_desktop_config.json` ([find your config path](docs/INSTALLATION.md)):
+
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "npx",
+      "args": ["-y", "@path58/n8n-mcp"]
+    }
+  }
+}
+```
+
+Then restart Claude Desktop.
+
+**Gemini CLI, global install, and other options:** [docs/INSTALLATION.md](docs/INSTALLATION.md)
+
+### 2. Try it
+
+Ask your AI assistant:
+
+> "What nodes does n8n have for sending Slack messages?"
+
+or
+
+> "Validate this n8n workflow JSON for me: { ... }"
+
+---
+
+## 8 MCP Tools
+
+### Validation (4 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `validate_workflow` | Run L1-L6 validation on workflow JSON — structure, nodes, credentials, connections, parameters, and patterns |
+| `get_operation_schema` | Get exact parameter requirements for any node operation — prevents hallucinated parameters |
+| `check_parameter` | Validate a specific parameter value in real-time — type checking, enum validation, typo detection |
+| `suggest_fix` | Get concrete fix suggestions for validation issues — rename, add, remove, or replace |
+
+### Discovery (4 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `list_nodes` | Browse and search 1,982 n8n nodes by category or keyword |
+| `list_operations` | List all operations for a node type, grouped by resource |
+| `get_node_info` | Get comprehensive node details — operations, credentials, properties |
+| `find_similar_pattern` | Search 9,000+ validated workflows for working examples |
+
+Full reference with input/output schemas: [docs/TOOLS.md](docs/TOOLS.md)
+
+---
+
+## What makes P58-n8n different
+
+**Ground-truth catalog.** Every parameter, operation, and connection rule comes from the actual n8n node catalog — not LLM guesses.
+
+**6-level validation.** L1 (structure) through L6 (flow patterns) catches problems before execution:
+
+```
+L1 Structure  →  L2 Nodes  →  L3 Credentials  →  L4 Connections  →  L5 Parameters  →  L6 Patterns
+   ~30ms          ~60ms         ~80ms              ~180ms             ~850ms            ~200ms
+```
+
+Full pipeline: ~1.4 seconds.
+
+**26 auto-fix rules.** Automatic repair for common issues — orphan connections, deprecated nodes, missing parameters, dead-end flows, and more.
+
+**9,000+ validated workflows.** Real working examples your AI can reference when building new workflows.
+
+---
+
+## Usage Examples
+
+See [docs/EXAMPLES.md](docs/EXAMPLES.md) for detailed walkthroughs:
+
+1. **Discover & Build** — Find the right nodes and build a Slack notification workflow
+2. **Validate & Fix** — Catch and repair issues in an existing workflow
+3. **Schema-Driven Generation** — Use operation schemas to generate correct parameters
+
+---
+
+## Architecture
+
+P58-n8n runs as a local stdio MCP server. No API keys or cloud services required.
+
+```
+AI Client (Claude/Gemini)
+    ↕ MCP Protocol (stdio)
+P58-n8n Server
+    ↕
+Validation Engine (L1-L6) + Node Catalog (1,982 nodes, 40,179 ops)
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full system design.
+
+---
+
+## Troubleshooting
+
+### Server not starting
+
+```bash
+# Verify Node.js 18+
+node --version
+
+# Test the server directly
+npx -y @path58/n8n-mcp
+# Should start without errors (it waits for MCP input on stdio)
+```
+
+### Tools not appearing in Claude Desktop
+
+1. Restart Claude Desktop after editing config
+2. Check config file path is correct for your OS
+3. Verify JSON syntax — trailing commas break it
+
+### "Command not found" errors
+
+```bash
+# Ensure Node.js and npx are available
+which npx
+
+# Or install globally instead
+npm install -g @path58/n8n-mcp
+p58-n8n  # Run directly
+```
+
+### ChatGPT Desktop
+
+ChatGPT Desktop is **not supported** — it requires HTTP/SSE transport, but P58-n8n uses stdio. See [docs/INSTALLATION.md](docs/INSTALLATION.md) for details.
+
+---
+
+## Contributing
+
+P58-n8n is currently in **soft launch** (friends & family). Feedback welcome:
+
+- **Issues:** [GitHub Issues](https://github.com/tsvika58/n8n-workflow-validator/issues)
+- **Email:** tvagman@gmail.com
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+**Built by [Path58](https://path58.com)**