@path58/p58-n8n 0.2.1 → 0.2.3

package/AGENT_INSTALL.md

@@ -1,124 +1,127 @@
-# P58-n8n — Drop & Install
+# p58-n8n — LLM Agent Installation Guide
 
-**For users:** Drop this file into any AI chat and say: **"Install this MCP server for me"**
+> **🤖 ACTION REQUIRED:** You are reading this because a user wants you to install the **p58-n8n** MCP server. Follow the steps below in order. You have everything you need in this file — do NOT search the web for additional instructions. If the user dropped a repo URL or README, this is the authoritative installation guide.
 
-**For AI agents:** Follow the instructions in the AI AGENT section below.
+> **Your job:** Detect the user's MCP client → find their n8n instance (if any) → write the config → restart → verify. Minimize questions to the user — auto-discover what you can, only ask when you must (API key, n8n URL if not found).
 
 ---
 
-## What you'll get
+## What is p58-n8n?
 
-P58-n8n gives your AI assistant deep n8n workflow knowledge — 1,982 nodes, 40,179 operations, 26 auto-fix rules.
+p58-n8n is an MCP server that gives LLMs the ability to validate, build, deploy, and manage n8n workflows. It provides 34 tools organized in tiers:
 
-| 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 |
+- **Tier 1 (offline):** `validate_workflow`, `list_nodes`, `get_operation_schema`, `suggest_fix`, `check_parameter` — work immediately, no env vars needed
+- **Tier 2-7 (require n8n):** `build_workflow`, `list_credentials`, `activate_workflow`, `execute_workflow`, `test_workflow`, `plan_workflow`, etc. — require connection to user's n8n instance
 
-### 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 |
+## Installation Decision Tree
+
+```
+Does the user have n8n running?
+├── YES → Full install (N8N_API_URL + N8N_API_KEY)
+│         All 34 tools work: validate, build, deploy, execute
+│
+└── NO / DON'T KNOW → Minimal install (no env vars)
+                       Tier 1 tools only: validate, list, check params
+                       User can add n8n config later
+```
 
 ---
 
-## AI AGENT: Follow These Instructions
+## Step 1: Detect the MCP Client
 
-### STEP 1 — Detect Environment
+Determine which AI client the user is using. Check for config files in this order:
 
-Determine your capabilities and the user's platform.
+| Client | Config File Path | OS |
+|--------|-----------------|-----|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | macOS |
+| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json` | Windows |
+| **Claude Desktop** | `~/.config/Claude/claude_desktop_config.json` | Linux |
+| **Claude Code** | Use `claude mcp add` CLI command | All |
+| **Cursor** | `~/.cursor/mcp.json` | All |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | All |
+| **VS Code (Copilot)** | `.vscode/mcp.json` in workspace | All |
 
-**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/
-```
+**Detection method:** Check if these files exist. If multiple exist, ask the user which client they want to configure.
 
 ---
 
-### STEP 2a — Auto-Install (can run commands)
+## Step 2: Find the User's n8n Instance
 
-**Prerequisites — verify first:**
+Try these methods in order:
 
+### Method A: Check environment variables
 ```bash
-node --version
-# Must be v18.0.0 or higher. If not installed, tell the user to install from https://nodejs.org/
+echo $N8N_API_URL
+echo $N8N_API_BASE_URL
+echo $N8N_HOST
 ```
 
-**Then install based on which client the user wants:**
-
-#### Claude Code
+### Method B: Probe common localhost ports
+```bash
+# Standard n8n port
+curl -s -o /dev/null -w "%{http_code}" http://localhost:5678/api/v1/workflows 2>/dev/null
+# Returns 401 = n8n is running (auth required) ✅
+# Returns 000 = n8n is not running at this address ❌
+```
 
-Run this single command:
+### Method C: Check Docker containers
+```bash
+docker ps --filter "name=n8n" --format "{{.Ports}}" 2>/dev/null
+# Example output: 0.0.0.0:5678->5678/tcp → n8n at localhost:5678
+```
 
+### Method D: Check running processes
 ```bash
-claude mcp add p58-n8n -- npx -y @path58/p58-n8n
+ps aux | grep -i n8n | grep -v grep
 ```
 
-Done. Skip to STEP 3.
+### Method E: Ask the user
+If none of the above work, ask: "What is the URL of your n8n instance? (e.g., http://localhost:5678 or https://n8n.example.com)"
 
-#### Claude Desktop (Cowork mode — can write files)
+**IMPORTANT:** The API URL must include the `/api/v1` suffix. Example: `http://localhost:5678/api/v1`
 
-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`
+## Step 3: Get the n8n API Key
 
-**If file exists:** Read it, parse the JSON, add this entry inside `mcpServers`:
+The API key cannot be auto-discovered. The user must provide it or create one.
 
-```json
-"p58-n8n": {
-  "command": "npx",
-  "args": ["-y", "@path58/p58-n8n"]
-}
-```
+**Instructions to give the user:**
+1. Open n8n in your browser (the URL from Step 2, without `/api/v1`)
+2. Go to **Settings → API Keys** (or **Settings → n8n API**)
+3. Click **Create an API key**
+4. Copy the key — it starts with `eyJ...` (JWT format)
+5. Share it with me so I can add it to your config
+
+**If the user can't find API Keys in Settings:** They may be on n8n Community Edition < 0.225.0 or n8n Cloud with API disabled. API key management requires admin access.
+
+---
 
-**If file doesn't exist:** Create it with:
+## Step 4: Write the Configuration
 
+### For Claude Desktop / Cursor / Windsurf / VS Code (JSON config)
+
+Read the existing config file, then add p58-n8n inside the `mcpServers` object. Do NOT overwrite existing MCP servers.
+
+**Full config (with n8n):**
 ```json
 {
   "mcpServers": {
     "p58-n8n": {
       "command": "npx",
-      "args": ["-y", "@path58/p58-n8n"]
+      "args": ["-y", "@path58/p58-n8n"],
+      "env": {
+        "N8N_API_URL": "http://localhost:5678/api/v1",
+        "N8N_API_KEY": "<paste-api-key-here>"
+      }
     }
   }
 }
 ```
 
-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:
-
+**Minimal config (validation only, no n8n needed):**
 ```json
 {
   "mcpServers": {
@@ -130,94 +133,103 @@ There is NO `gemini mcp add` command. Edit the config file directly.
 }
 ```
 
----
+### For Claude Code (CLI)
 
-### STEP 2b — Guided Install (chat-only)
+**Full config:**
+```bash
+claude mcp add p58-n8n \
+  -e N8N_API_URL=http://localhost:5678/api/v1 \
+  -e N8N_API_KEY=<paste-api-key-here> \
+  -- npx -y @path58/p58-n8n
+```
 
-Ask the user which client they want to set up, then give them copy-paste instructions.
+**Minimal config:**
+```bash
+claude mcp add p58-n8n -- npx -y @path58/p58-n8n
+```
 
-**Ask:** "Which AI client do you want to use P58-n8n with?"
+---
 
-#### For Claude Desktop
+## Step 5: Restart the Client
 
-Tell the user:
+The MCP server config is only read at startup. After writing the config:
 
-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`
+| Client | Restart Method |
+|--------|---------------|
+| **Claude Desktop** | Quit completely (Cmd+Q on macOS), then reopen |
+| **Claude Code** | Exit and restart the CLI session |
+| **Cursor** | Restart Cursor (Cmd+Shift+P → Reload Window) |
+| **Windsurf** | Restart Windsurf |
 
-2. Add this inside the `mcpServers` object (create the file if it doesn't exist):
+**CRITICAL:** On macOS, closing the window is NOT enough for Claude Desktop. The user must Cmd+Q to fully quit.
 
-```json
-{
-  "mcpServers": {
-    "p58-n8n": {
-      "command": "npx",
-      "args": ["-y", "@path58/p58-n8n"]
-    }
-  }
-}
-```
+---
 
-3. Restart Claude Desktop.
+## Step 6: Verify Installation
 
-#### For Claude Code
+After restart, run these verification steps:
 
-Tell the user to run:
+### Check 1: Tool availability
+Ask: "List n8n nodes for sending email"
+- **Expected:** The LLM calls `list_nodes` and returns results
+- **If tools not visible:** Config file has syntax error or wrong path
 
-```bash
-claude mcp add p58-n8n -- npx -y @path58/p58-n8n
-```
+### Check 2: n8n connectivity (if configured)
+Ask: "Check n8n server health"
+- **Expected:** `connected: true` with server version
+- **If `connected: false`:** Check N8N_API_URL — is n8n actually running at that address?
+- **If `Authentication failed`:** Check N8N_API_KEY — is it valid?
 
-#### For Gemini CLI
+### Check 3: Full pipeline (if n8n connected)
+Ask: "List my n8n credentials"
+- **Expected:** Returns list of configured credentials
+- **If error:** API key may be expired or n8n needs restart
 
-Tell the user:
+---
 
-1. Open `~/.gemini/settings.json` (create if needed)
-2. Add:
+## Environment Variables Reference
 
-```json
-{
-  "mcpServers": {
-    "p58-n8n": {
-      "command": "npx",
-      "args": ["-y", "@path58/p58-n8n"]
-    }
-  }
-}
-```
+| Variable | Required? | Description | How to find |
+|----------|-----------|-------------|-------------|
+| `N8N_API_URL` | For Tier 2-7 tools | n8n instance API URL | See Step 2 above |
+| `N8N_API_KEY` | For Tier 2-7 tools | n8n API authentication key | n8n → Settings → API Keys |
 
-#### For ChatGPT Desktop
+> **Note:** `N8N_API_BASE_URL` is accepted as a fallback for `N8N_API_URL`. If neither is set, defaults to `http://localhost:5678/api/v1`.
 
-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.
+### Variables NOT needed for standard installation
+
+| Variable | Purpose | Who needs it |
+|----------|---------|-------------|
+| `P58_DATABASE_URL` | Extended catalog enrichment | Path58 internal / advanced users only |
+| `NODE_ENV` | Logger behavior | Not needed (server handles this) |
+| `NO_COLOR` | Disable ANSI colors | Not needed (server strips automatically since v0.2.2) |
 
 ---
 
-### STEP 3 — Verify Installation
+## Troubleshooting
 
-After setup, test with this prompt:
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Tools not appearing | Config syntax error | Validate JSON (check trailing commas, unclosed braces) |
+| Tools not appearing | Wrong config file path | Verify OS-specific path from Step 1 |
+| "npx: command not found" | Node.js not installed | Install from https://nodejs.org/ |
+| "Authentication failed" on deploy tools | N8N_API_KEY missing or invalid | Add API key to config, restart client |
+| "Connection refused" on server_health | n8n not running at configured URL | Start n8n or fix N8N_API_URL |
+| All tools timeout | Firewall blocking localhost | Check firewall / VPN settings |
+| Server shows "failed" status | ANSI color issue (pre-v0.2.2) | Update to latest version: `npx -y @path58/p58-n8n@latest` |
 
-> "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.
+## Post-Install: What the User Can Do
 
-**If it doesn't work:**
+Once installed, the user can ask their AI assistant to:
 
-```
-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/p58-n8n
-
-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/p58-n8n (reinstall)
-```
+- **"Validate this n8n workflow JSON"** — Tier 1, works immediately
+- **"What parameters does the Slack node need?"** — Tier 1, works immediately
+- **"Build me a workflow that sends Slack when Gmail receives an email"** — Tier 2+, needs n8n
+- **"List my n8n credentials"** — Tier 2+, needs n8n
+- **"Deploy and test this workflow"** — Tier 2+, needs n8n
 
 ---
 
-**Package:** `@path58/p58-n8n` | **License:** MIT | **Built by [Path58](https://path58.com)**
+**Package:** `@path58/p58-n8n` | **npm:** https://www.npmjs.com/package/@path58/p58-n8n | **Version:** 0.2.2+

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.2.2] - 2026-03-09
+
+### Fixed
+
+- ANSI color escape codes from logger no longer corrupt the MCP JSON-RPC stream on stdout
+- `console.log` redirected to `console.error` at bundle entry — logger output goes to stderr (diagnostics), not stdout (protocol channel)
+- ANSI escape codes stripped from stderr output when not connected to a TTY, preventing parse errors in Claude Desktop and other MCP hosts
+
 ## [0.2.1] - 2026-03-09
 
 ### Fixed
@@ -90,6 +98,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - npm package published as `@path58/p58-n8n`
 - ESM module support with shebang for direct `npx` execution
 
+[0.2.2]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.2.2
 [0.2.1]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.2.1
 [0.2.0]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.2.0
 [0.1.1]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.1.1

package/README.md

@@ -8,6 +8,8 @@
 
 p58-n8n is an MCP server that gives your AI assistant deep knowledge of n8n — **1,545 nodes**, **12,619 operations**, **38,005 parameter rules** — so it can plan, build, validate, fix, and deploy workflows correctly. No manual iteration. No broken JSON.
 
+> **🤖 AI Agent?** If you are an LLM assistant and a user asked you to install this MCP server, **stop here and read [`AGENT_INSTALL.md`](https://github.com/tsvika58/n8n-workflow-validator/blob/main/AGENT_INSTALL.md)** — it has the complete autonomous installation guide with client detection, n8n auto-discovery, config templates for all clients, and verification steps. Everything you need to install p58-n8n without asking the user unnecessary questions.
+
 ---
 
 ## Quick Start (< 2 minutes)
@@ -28,7 +30,10 @@ npm install -g @path58/p58-n8n
 
 **Claude Code** (one command):
 ```bash
-claude mcp add p58-n8n -- npx -y @path58/p58-n8n
+claude mcp add p58-n8n \
+  -e N8N_API_URL=http://localhost:5678/api/v1 \
+  -e N8N_API_KEY=your-n8n-api-key \
+  -- npx -y @path58/p58-n8n
 ```
 
 **Claude Desktop** — add to `claude_desktop_config.json`:
@@ -37,16 +42,26 @@ claude mcp add p58-n8n -- npx -y @path58/p58-n8n
   "mcpServers": {
     "p58-n8n": {
       "command": "npx",
-      "args": ["-y", "@path58/p58-n8n"]
+      "args": ["-y", "@path58/p58-n8n"],
+      "env": {
+        "N8N_API_URL": "http://localhost:5678/api/v1",
+        "N8N_API_KEY": "your-n8n-api-key"
+      }
     }
   }
 }
 ```
 
+Get your API key from **n8n → Settings → API Keys**.
+
 Config file location: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Restart Claude Desktop after saving.
 
+> **Note:** Validation tools (`validate_workflow`, `list_nodes`, etc.) work immediately without any env vars. The `N8N_API_URL` and `N8N_API_KEY` are only needed for deploy, execute, and credential tools.
+
 **Cursor / Windsurf** — see [docs/INSTALLATION.md](docs/INSTALLATION.md) for full multi-client setup.
 
+**LLM-assisted setup** — if you're an AI agent helping a user install p58-n8n, read [AGENT_INSTALL.md](https://github.com/tsvika58/n8n-workflow-validator/blob/main/AGENT_INSTALL.md) for the autonomous installation guide.
+
 ### 3. Try it
 
 ```

package/dist/mcp/server.bundle.cjs

@@ -1,4 +1,24 @@
 #!/usr/bin/env node
+
+// ── MCP stdio transport protection ──────────────────────────────────
+// Redirect console.log → stderr (stdout is JSON-RPC channel)
+var __origLog = console.log.bind(console);
+console.log = function() { console.error.apply(console, arguments); };
+
+// Strip ANSI escape codes when stderr is not a TTY
+if (!process.stderr.isTTY) {
+  var __origStderrWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = function(chunk, enc, cb) {
+    if (typeof chunk === 'string') {
+      chunk = chunk.replace(/\x1b\[[0-9;]*m/g, '');
+    } else if (Buffer.isBuffer(chunk)) {
+      chunk = Buffer.from(chunk.toString().replace(/\x1b\[[0-9;]*m/g, ''));
+    }
+    return __origStderrWrite(chunk, enc, cb);
+  };
+}
+// ── End MCP stdio transport protection ──────────────────────────────
+
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -32,6 +52,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // node_modules/consola/dist/core.cjs
 var require_core = __commonJS({
@@ -18413,6 +18434,12 @@ var init_cached_catalog_adapter = __esm({
 });
 
 // dist/mcp/server.js
+var server_exports = {};
+__export(server_exports, {
+  TIER_1_TOOLS: () => TIER_1_TOOLS,
+  logStartupSummary: () => logStartupSummary
+});
+module.exports = __toCommonJS(server_exports);
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_types22 = require("@modelcontextprotocol/sdk/types.js");
@@ -18421,7 +18448,7 @@ var import_types22 = require("@modelcontextprotocol/sdk/types.js");
 var config = {
   // Server identity
   SERVER_NAME: "p58-n8n",
-  SERVER_VERSION: "0.2.1",
+  SERVER_VERSION: "0.2.3",
   // Database configuration (from environment)
   SUPABASE_URL: process.env.SUPABASE_URL,
   SUPABASE_KEY: process.env.SUPABASE_KEY,
@@ -18707,6 +18734,7 @@ var collectConfigSchema = import_zod.z.object({
   config_requirements: import_zod.z.array(configRequirementItemSchema).optional().describe("Config requirements from plan_workflow response (preferred over workflow_json). Pass the configRequirements array directly from plan_workflow output."),
   user_responses: import_zod.z.record(import_zod.z.unknown()).optional().describe('User-provided values keyed by "nodeType:parameterName" (from question.id). Example: { "n8n-nodes-base.googleSheets:spreadsheetId": "1BxiMVs0..." }. Omit to get questions without providing values (first turn of multi-turn collection).')
 });
+var setupCheckSchema = import_zod.z.object({});
 var toolSchemas = {
   test_workflow: testWorkflowSchema,
   validate_workflow: validateWorkflowSchema,
@@ -18741,7 +18769,8 @@ var toolSchemas = {
   test_credential: testCredentialSchema,
   update_credential: updateCredentialSchema,
   delete_credential: deleteCredentialSchema,
-  collect_config: collectConfigSchema
+  collect_config: collectConfigSchema,
+  setup_check: setupCheckSchema
 };
 
 // dist/mcp/tools/validate.js
@@ -38805,6 +38834,16 @@ async function warmCredentialCache() {
     import_logging42.logger.warn("credential-cache: warm-up failed (non-fatal)", { error: String(error) });
   }
 }
+function getCredentialCacheStatus() {
+  if (!cacheState) {
+    return { loaded: false, count: 0, expires_at: null };
+  }
+  return {
+    loaded: true,
+    count: cacheState.credentials.length,
+    expires_at: new Date(cacheState.expires_at).toISOString()
+  };
+}
 function clearCredentialCache() {
   cacheState = null;
 }
@@ -44071,6 +44110,161 @@ When values are collected, marks matching factory.gaps entries as resolved for a
   }
 };
 
+// dist/mcp/tools/handlers/shared/n8n-guard.js
+var SETUP_GUIDE_URL = "https://github.com/tsvika58/n8n-workflow-validator/blob/main/docs/AGENT_INSTALL.md";
+var OFFLINE_TOOLS = /* @__PURE__ */ new Set([
+  "validate_workflow",
+  "get_operation_schema",
+  "check_parameter",
+  "suggest_fix",
+  "list_operations",
+  "list_nodes",
+  "get_node_info",
+  "find_similar_pattern",
+  "get_session_metrics",
+  "get_credential_schema",
+  "setup_check"
+]);
+function requiresN8nApiKey(toolName) {
+  return !OFFLINE_TOOLS.has(toolName);
+}
+function makeN8nNotConfiguredError() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: `This tool requires n8n connection. Set N8N_API_URL and N8N_API_KEY in your MCP config. See: ${SETUP_GUIDE_URL}`
+        })
+      }
+    ],
+    isError: true
+  };
+}
+
+// dist/mcp/tools/handlers/setup-check.js
+var SETUP_GUIDE_URL2 = "https://github.com/tsvika58/n8n-workflow-validator/blob/main/docs/AGENT_INSTALL.md";
+var N8N_PROBE_TIMEOUT_MS = 2e3;
+var N8N_PROBE_PORTS = [5678, 5679];
+async function probeN8nUrl(url2) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), N8N_PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(url2, { signal: controller.signal });
+    const needs_api_key = response.status === 401 || response.status === 403;
+    return { url: url2, status: response.status, needs_api_key, reachable: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      url: url2,
+      status: null,
+      needs_api_key: false,
+      reachable: false,
+      error: message.includes("abort") ? "timeout" : message
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function discoverN8nInstances() {
+  const probeUrls = N8N_PROBE_PORTS.map((port) => `http://localhost:${port}/api/v1/workflows`);
+  return Promise.all(probeUrls.map(probeN8nUrl));
+}
+function buildToolCounts() {
+  const total = getRegisteredTools().length;
+  const tier1 = OFFLINE_TOOLS.size;
+  return { tier1, tier2_7: total - tier1 };
+}
+function collectIssues(apiKeySet, n8nConnected, probes) {
+  const issues = [];
+  if (!apiKeySet) {
+    issues.push("N8N_API_KEY not set \u2014 Tier 2-7 deploy tools unavailable");
+  }
+  const apiUrlSet = Boolean(process.env.N8N_API_URL ?? process.env.N8N_API_BASE_URL);
+  if (!apiUrlSet && probes) {
+    const reachable = probes.filter((p) => p.reachable);
+    if (reachable.length > 0) {
+      const probeUrl = reachable[0].url.replace("/api/v1/workflows", "");
+      issues.push(`N8N_API_URL not set \u2014 n8n detected at ${probeUrl}. Set N8N_API_URL=${probeUrl}/api/v1 in your MCP config.`);
+    } else {
+      issues.push("N8N_API_URL not set \u2014 no n8n instance detected on localhost:5678 or localhost:5679");
+    }
+  }
+  if (apiKeySet && !n8nConnected) {
+    issues.push("N8N_API_KEY is set but n8n is unreachable \u2014 check N8N_API_URL and ensure n8n is running");
+  }
+  return issues;
+}
+async function buildReport() {
+  const apiKeySet = Boolean(process.env.N8N_API_KEY);
+  const n8nUrl = process.env.N8N_API_URL ?? process.env.N8N_API_BASE_URL ?? null;
+  const cacheStatus = getCredentialCacheStatus();
+  const n8nConnected = cacheStatus.loaded;
+  const credentialCount = cacheStatus.loaded ? cacheStatus.count : null;
+  let probes;
+  if (!n8nUrl) {
+    probes = await discoverN8nInstances();
+  }
+  const issues = collectIssues(apiKeySet, n8nConnected, probes);
+  const toolCounts = buildToolCounts();
+  const report = {
+    server_version: config.SERVER_VERSION,
+    n8n_configured: apiKeySet,
+    n8n_url: n8nUrl,
+    n8n_connected: n8nConnected,
+    n8n_api_key_set: apiKeySet,
+    credential_count: credentialCount,
+    catalog_ready: true,
+    tools_available: toolCounts,
+    issues,
+    setup_guide: SETUP_GUIDE_URL2
+  };
+  if (probes) {
+    report.n8n_probes = probes.map((p) => ({
+      ...p,
+      url: p.url.replace("/api/v1/workflows", "/api/v1")
+    }));
+  }
+  return report;
+}
+async function handleSetupCheck(_args) {
+  try {
+    const report = await buildReport();
+    return {
+      content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: `setup_check failed: ${message}` }) }],
+      isError: true
+    };
+  }
+}
+var setupCheckToolDefinition = {
+  name: "setup_check",
+  description: `Run this first to check what's configured and what's missing.
+
+Returns a diagnostic report including:
+- Server version
+- n8n connection status (configured/connected/unreachable)
+- n8n URL (from env var or auto-detected)
+- Credential count (if n8n is connected)
+- Tool availability by tier
+- List of issues with actionable guidance
+- Link to the setup guide
+
+When N8N_API_URL is not set, automatically probes localhost:5678 and localhost:5679
+to detect a local n8n installation.
+
+Use this after installation to verify everything is working, or to diagnose
+connection problems.`,
+  inputSchema: {
+    type: "object",
+    properties: {}
+  }
+};
+
 // dist/mcp/tools/index.js
 var toolRegistry = /* @__PURE__ */ new Map();
 var TOOL_ENTRIES = [
@@ -44107,7 +44301,8 @@ var TOOL_ENTRIES = [
   { name: "test_credential", definition: testCredentialToolDefinition, handler: handleTestCredential },
   { name: "update_credential", definition: updateCredentialToolDefinition, handler: handleUpdateCredential },
   { name: "delete_credential", definition: deleteCredentialToolDefinition, handler: handleDeleteCredential },
-  { name: "collect_config", definition: collectConfigToolDefinition, handler: handleCollectConfig }
+  { name: "collect_config", definition: collectConfigToolDefinition, handler: handleCollectConfig },
+  { name: "setup_check", definition: setupCheckToolDefinition, handler: handleSetupCheck }
 ];
 function registerTool(tool) {
   if (!hasSchema(tool.name)) {
@@ -44135,6 +44330,9 @@ async function dispatchToolCall(name, args) {
   const tool = toolRegistry.get(name);
   if (!tool)
     return buildUnknownToolResponse(name);
+  if (requiresN8nApiKey(name) && !process.env.N8N_API_KEY) {
+    return makeN8nNotConfiguredError();
+  }
   if (tool.inputSchema && hasSchema(name)) {
     const validation = validateToolInput(name, args);
     if (!validation.success)
@@ -44363,6 +44561,39 @@ function registerShutdownHandlers(serverName, deps) {
 }
 
 // dist/mcp/server.js
+var TIER_1_TOOLS = /* @__PURE__ */ new Set([
+  "validate_workflow",
+  "get_operation_schema",
+  "check_parameter",
+  "suggest_fix",
+  "list_operations",
+  "list_nodes",
+  "get_node_info",
+  "find_similar_pattern"
+]);
+var SETUP_GUIDE_URL3 = "https://github.com/tsvika58/n8n-workflow-validator/blob/main/docs/AGENT_INSTALL.md";
+function logStartupSummary(n8nConnected) {
+  const apiKey = process.env.N8N_API_KEY;
+  const n8nUrl = process.env.N8N_API_URL ?? process.env.N8N_API_BASE_URL ?? "http://localhost:5678/api/v1";
+  const totalTools = getRegisteredTools().length;
+  const tier1Count = TIER_1_TOOLS.size;
+  const tier27Count = totalTools - tier1Count;
+  let n8nStatus;
+  if (!apiKey) {
+    n8nStatus = "not configured (set N8N_API_URL and N8N_API_KEY for deploy tools)";
+  } else if (n8nConnected) {
+    n8nStatus = `connected (${n8nUrl})`;
+  } else {
+    n8nStatus = `configured but unreachable (${n8nUrl})`;
+  }
+  const tier27Status = apiKey && n8nConnected ? `${tier27Count} tools ready` : `${tier27Count} tools unavailable (no N8N_API_KEY)`;
+  console.error(`n8n: ${n8nStatus}`);
+  console.error(`catalog: ready`);
+  console.error(`Tier 1: ${tier1Count} tools ready | Tier 2-7: ${tier27Status}`);
+  if (!apiKey) {
+    console.error(`Setup guide: ${SETUP_GUIDE_URL3}`);
+  }
+}
 var server = new import_server.Server({
   name: config.SERVER_NAME,
   version: config.SERVER_VERSION
@@ -44397,13 +44628,20 @@ async function main() {
   await server.connect(transport);
   const toolCount = getRegisteredTools().length;
   console.error(`${config.SERVER_NAME} v${config.SERVER_VERSION} running on stdio (${toolCount} tools registered)`);
+  logStartupSummary(Boolean(process.env.N8N_API_KEY));
   registerShutdownHandlers(config.SERVER_NAME);
-  warmCredentialCache().catch((e) => console.error("Credential cache warm-up failed:", e));
+  void warmCredentialCache().catch(() => {
+  });
 }
 main().catch((error) => {
   console.error("Server failed to start:", error);
   process.exit(1);
 });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TIER_1_TOOLS,
+  logStartupSummary
+});
 /*! Bundled license information:
 
 mime-db/index.js:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path58/p58-n8n",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The smartest and fastest n8n MCP server — validate, fix, and discover workflows inside your LLM",
   "keywords": [
     "mcp",
@@ -13,6 +13,7 @@
   ],
   "author": "Path58",
   "license": "MIT",
+  "homepage": "https://github.com/tsvika58/n8n-workflow-validator#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tsvika58/n8n-workflow-validator.git"