@path58/p58-n8n 0.2.2 → 0.2.4

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 35 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 |
+| **Gemini CLI** | `~/.gemini/settings.json` or `~/.gemini/antigravity/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 / Gemini CLI / 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) |
+| **Gemini CLI** | Exit and restart the CLI session, or use the MCP refresh command |
 
-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.4+

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.4] - 2026-03-10
+
+### Added
+
+- **Lazy initialization** — MCP server defers tool registration and fixer registry loading until after stdio handshake completes; eliminates cold-start timeouts on strict-timeout clients (Gemini CLI / Antigravity)
+- **`setup_check` tool** — new Tier 7 diagnostic tool that validates server health, n8n connectivity, and database access in a single call; total tools now **35** across 7 tiers
+- **Gemini CLI support** — installation guide and documentation updated with Gemini CLI / Antigravity configuration examples
+
+### Changed
+
+- Documentation overhauled for v0.2.4: replaced Windsurf references with Gemini CLI throughout AGENT_INSTALL.md, README.md, and FRIEND_ONBOARDING.md
+- Fixed broken `docs/INSTALLATION.md` links in README (file never existed) — now point to AGENT_INSTALL.md
+- Standardized `N8N_API_URL` environment variable naming across all documentation
+- Updated catalog counts in documentation: 1,545 nodes, 679 credentials, 35 tools
+
+### Fixed
+
+- Server initialization no longer blocks the MCP handshake — clients with < 5s timeouts can now connect reliably
+- Startup version banner now correctly reports v0.2.4
+- **Friend & family UX hardening** — 5 catalog tool handlers now return `CATALOG_UNREACHABLE` or `DB_NOT_CONFIGURED` with setup guide URLs instead of opaque "internal error" when database issues occur
+- DB pool auto-sizes for catalog-only users (max 3 connections, no keepAlive) — prevents resource exhaustion for friends without n8n
+- Startup health check confirms database connectivity before accepting tool calls
+- Shutdown race condition eliminated — in-flight request tracker waits up to 5s for active queries before pool disposal
+- `makeDbNotConfiguredResponse` now includes `isError: true` flag so LLMs recognize the error
+- `plan_workflow` description updated to note that `build_workflow` requires n8n API access
+
+## [0.2.3] - 2026-03-09
+
+### Fixed
+
+- Internal release — build and bundle pipeline fixes
+
 ## [0.2.2] - 2026-03-09
 
 ### Fixed
@@ -98,8 +130,10 @@ 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
-[0.1.0]: https://github.com/tsvika58/n8n-workflow-validator/releases/tag/v0.1.0
+[0.2.4]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.2.4
+[0.2.3]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.2.3
+[0.2.2]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.2.2
+[0.2.1]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.2.1
+[0.2.0]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.2.0
+[0.1.1]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.1.1
+[0.1.0]: https://github.com/tsvika58/p58-n8n/releases/tag/v0.1.0

package/README.md

@@ -4,10 +4,12 @@
 
 [![npm](https://img.shields.io/npm/v/@path58/p58-n8n)](https://www.npmjs.com/package/@path58/p58-n8n)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://github.com/tsvika58/n8n-workflow-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/tsvika58/n8n-workflow-validator/actions/workflows/ci.yml)
+[![Tests](https://github.com/tsvika58/p58-n8n/actions/workflows/ci.yml/badge.svg)](https://github.com/tsvika58/p58-n8n/actions/workflows/ci.yml)
 
 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/p58-n8n/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`:
@@ -39,16 +44,23 @@ claude mcp add p58-n8n -- npx -y @path58/p58-n8n
       "command": "npx",
       "args": ["-y", "@path58/p58-n8n"],
       "env": {
-        "P58_DATABASE_URL": "your-supabase-connection-string"
+        "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.
 
-**Cursor / Windsurf** — see [docs/INSTALLATION.md](docs/INSTALLATION.md) for full multi-client setup.
+> **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 / Gemini CLI** — same JSON format, add to your client's MCP config file. See [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for all supported clients.
+
+**LLM-assisted setup** — if you're an AI agent helping a user install p58-n8n, read [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for the autonomous installation guide.
 
 ### 3. Try it
 
@@ -114,7 +126,7 @@ p58-n8n uses 80% less token context than n8n-mcp by serving structured catalog d
 
 ---
 
-## 34 Tools in 7 Tiers
+## 35 Tools in 7 Tiers
 
 ### Tier 1 — Validation & Analysis
 
@@ -184,6 +196,7 @@ p58-n8n uses 80% less token context than n8n-mcp by serving structured catalog d
 | Tool | What it does |
 |------|-------------|
 | `collect_config` | Detect missing node configuration from your live n8n instance (covers 2,494 known gaps) |
+| `setup_check` | Diagnostic report — server version, n8n connectivity, credential count, tool availability |
 
 Full reference with input/output schemas: [docs/TOOLS.md](docs/TOOLS.md)
 
@@ -223,11 +236,11 @@ p58-n8n will: call `get_credential_schema` for Slack → `create_credential` wit
 
 ## Installation
 
-See [docs/INSTALLATION.md](docs/INSTALLATION.md) for full setup instructions:
+See [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for full setup instructions:
 
 - Claude Desktop (macOS, Windows, Linux)
 - Claude Code (one-command setup)
-- Cursor and Windsurf
+- Cursor and Gemini CLI
 - Global install vs npx
 - Troubleshooting
 
@@ -262,7 +275,7 @@ MIT — see [LICENSE](LICENSE) for details.
 
 p58-n8n is in **soft launch** (friends & family). Issues and feedback welcome:
 
-- **Bugs:** [GitHub Issues](https://github.com/tsvika58/n8n-workflow-validator/issues)
+- **Bugs:** [GitHub Issues](https://github.com/tsvika58/p58-n8n/issues)
 - **Email:** tvagman@gmail.com
 
 ---
@@ -272,7 +285,7 @@ p58-n8n is in **soft launch** (friends & family). Issues and feedback welcome:
 p58-n8n runs as a local stdio MCP server. No cloud services required for basic use.
 
 ```
-AI Client (Claude / Cursor / Windsurf)
+AI Client (Claude / Cursor / Gemini CLI)
     ↕ MCP Protocol (stdio)
 p58-n8n Server
     ├── Validation Engine (L1-L6, ~1.4s)

package/dist/mcp/server.bundle.cjs

@@ -52,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({
@@ -3013,22 +3014,28 @@ function buildPoolOptions() {
 }
 function createPool(cfg) {
   const timeoutMs = getEnvNumber("DB_STATEMENT_TIMEOUT_MS", 3e4);
+  const isCatalogOnly = !!(process.env.P58_DATABASE_URL || process.env.MCP_DATABASE_URL) && !process.env.N8N_API_KEY;
   const pool = new import_pg.Pool({
     host: cfg.host,
     port: resolvePoolPort(cfg),
     user: cfg.user,
     password: cfg.password,
     database: cfg.database,
-    max: getEnvNumber("VALIDATOR_DB_POOL_MAX", 10),
-    min: getEnvNumber("VALIDATOR_DB_POOL_MIN", 1),
+    // Friends: 3 max (1 active + 2 burst). Full mode: 10.
+    max: getEnvNumber("VALIDATOR_DB_POOL_MAX", isCatalogOnly ? 3 : 10),
+    // Friends: 0 min — don't hold connections when idle. Full mode: 1.
+    min: getEnvNumber("VALIDATOR_DB_POOL_MIN", isCatalogOnly ? 0 : 1),
     // allowExitOnIdle: true — prevents zombie processes when MCP session ends (RAG-4.35.5)
-    idleTimeoutMillis: 6e4,
-    connectionTimeoutMillis: 15e3,
+    // Friends: 30s idle (release fast). Full mode: 60s.
+    idleTimeoutMillis: isCatalogOnly ? 3e4 : 6e4,
+    // Friends: 10s connect timeout (fail fast). Full mode: 15s.
+    connectionTimeoutMillis: isCatalogOnly ? 1e4 : 15e3,
     statement_timeout: timeoutMs,
     options: buildPoolOptions(),
     allowExitOnIdle: true,
-    keepAlive: true,
-    keepAliveInitialDelayMillis: 1e4
+    // Friends: no keepAlive (let connections close naturally). Full mode: keepAlive.
+    keepAlive: !isCatalogOnly,
+    ...isCatalogOnly ? {} : { keepAliveInitialDelayMillis: 1e4 }
   });
   pool.on("error", (err) => {
     console.warn(`[pg-pool] Idle connection error (non-fatal): ${err.message}`);
@@ -3040,6 +3047,24 @@ function getValidatorPool() {
     validatorPool = createPool(getValidatorDbConfig());
   return validatorPool;
 }
+async function warmSingleConnection(pool) {
+  const client = await pool.connect();
+  await client.query("SELECT 1");
+  client.release();
+}
+async function warmValidatorPool() {
+  if (poolWarmed)
+    return;
+  const pool = getValidatorPool();
+  const minConns = getEnvNumber("VALIDATOR_DB_POOL_MIN", 1);
+  try {
+    for (let i = 0; i < minConns; i++)
+      await warmSingleConnection(pool);
+    poolWarmed = true;
+  } catch (error) {
+    console.warn("Validator pool warm-up failed, continuing with lazy connection creation:", error);
+  }
+}
 async function validatorQuery(sql, params = []) {
   const client = await getValidatorPool().connect();
   const onClientError = (err) => {
@@ -3061,7 +3086,7 @@ async function shutdownValidatorPool() {
     validatorPool = null;
   }
 }
-var import_pg, dotenv, path, import_url, import_connection, __filename, __dirname, PROJECT_ROOT, validatorPool;
+var import_pg, dotenv, path, import_url, import_connection, __filename, __dirname, PROJECT_ROOT, validatorPool, poolWarmed;
 var init_validatorPostgresClient = __esm({
   "dist/db/validatorPostgresClient.js"() {
     "use strict";
@@ -3076,6 +3101,7 @@ var init_validatorPostgresClient = __esm({
     dotenv.config({ path: path.resolve(PROJECT_ROOT, ".env.supabase") });
     dotenv.config({ path: path.resolve(PROJECT_ROOT, ".env") });
     validatorPool = null;
+    poolWarmed = false;
   }
 });
 
@@ -18433,6 +18459,12 @@ var init_cached_catalog_adapter = __esm({
 });
 
 // dist/mcp/server.js
+var server_exports = {};
+__export(server_exports, {
+  isServerInitialized: () => isServerInitialized,
+  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");
@@ -18441,7 +18473,7 @@ var import_types22 = require("@modelcontextprotocol/sdk/types.js");
 var config = {
   // Server identity
   SERVER_NAME: "p58-n8n",
-  SERVER_VERSION: "0.2.2",
+  SERVER_VERSION: "0.2.4",
   // Database configuration (from environment)
   SUPABASE_URL: process.env.SUPABASE_URL,
   SUPABASE_KEY: process.env.SUPABASE_KEY,
@@ -18727,6 +18759,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,
@@ -18761,7 +18794,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
@@ -19171,6 +19205,30 @@ async function injectResponseMetadata(sessionId, toolName, response, executionSt
   return instrumented;
 }
 
+// dist/mcp/in-flight-tracker.js
+var inflightCount = 0;
+function incrementInflight() {
+  inflightCount++;
+}
+function decrementInflight() {
+  if (inflightCount > 0)
+    inflightCount--;
+}
+function waitForInflightRequests(timeoutMs) {
+  if (inflightCount === 0)
+    return Promise.resolve();
+  return new Promise((resolve2) => {
+    const deadline = setTimeout(resolve2, timeoutMs);
+    const poll = setInterval(() => {
+      if (inflightCount <= 0) {
+        clearInterval(poll);
+        clearTimeout(deadline);
+        resolve2();
+      }
+    }, 50);
+  });
+}
+
 // dist/validation/l1-structure.js
 async function validateL1Structure(workflowJson) {
   const startTime = performance.now();
@@ -30380,7 +30438,13 @@ var AutoFixerRegistry = class _AutoFixerRegistry {
     }
   }
 };
-var fixerRegistry = new AutoFixerRegistry();
+var _fixerRegistry = null;
+function getFixerRegistry() {
+  if (!_fixerRegistry) {
+    _fixerRegistry = new AutoFixerRegistry();
+  }
+  return _fixerRegistry;
+}
 
 // node_modules/axios/lib/helpers/bind.js
 function bind(fn, thisArg) {
@@ -34878,7 +34942,7 @@ async function runAutofixOnWorkflow(workflowJson, issues) {
   const { applied: credApplied, changelog: credChangelog } = preAssignCredentials(workflow, issues);
   const errorIssues = issues.filter((i) => i.severity === "error");
   const problems = errorIssues.map(issueToValidationProblem);
-  const fixResult = await fixerRegistry.applyFixes(workflow, problems);
+  const fixResult = await getFixerRegistry().applyFixes(workflow, problems);
   const fixChangelog = buildChangelog(fixResult.results);
   return {
     fixedWorkflow: fixResult.workflow,
@@ -35273,10 +35337,10 @@ How it works:
 
 Validation levels:
 - L1: JSON structure, required fields, duplicate node names
-- L2: Node types exist in catalog (1,982 nodes)
-- L3: Credential types valid (654 credentials) \u2014 includes available_credentials lookup
-- L4: Connection patterns exist (6,900 rules)
-- L5: Required parameters configured (35,143 params)
+- L2: Node types exist in catalog (1,545 nodes)
+- L3: Credential types valid (679 credentials) \u2014 includes available_credentials lookup
+- L4: Connection patterns exist (7,642 rules)
+- L5: Required parameters configured (38,005 params)
 - L6: Pattern validation (flow integrity, security, expressions)
 
 Returns detailed issues with severity, location, and suggested fixes.
@@ -35479,7 +35543,7 @@ var getOperationSchemaToolDefinition = {
   name: "get_operation_schema",
   description: `Get parameter requirements for a specific n8n node operation.
 
-Returns the exact required and optional parameters from our 35,143 parameter catalog.
+Returns the exact required and optional parameters from our 38,005 parameter catalog.
 Use this to prevent parameter hallucination when generating n8n workflows.
 
 Examples:
@@ -36565,6 +36629,77 @@ Examples:
   }
 };
 
+// dist/mcp/tools/handlers/shared/n8n-guard.js
+var SETUP_GUIDE_URL = "https://github.com/tsvika58/p58-n8n/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
+  };
+}
+function isDbConfigError(error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  return msg.includes("Missing required validator DB environment variable");
+}
+function isDbConnectionError(error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  return msg.includes("ECONNREFUSED") || msg.includes("ETIMEDOUT") || msg.includes("connect ETIMEDOUT") || msg.includes("after calling end on the pool") || msg.includes("Connection terminated") || msg.includes("getaddrinfo ENOTFOUND") || msg.includes("too many connections") || msg.includes("remaining connection slots");
+}
+function makeDbNotConfiguredResponse() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "DB_NOT_CONFIGURED",
+          message: "Catalog features require P58_DATABASE_URL. Set P58_DATABASE_URL in your MCP config to enable this tool.",
+          setup_guide: SETUP_GUIDE_URL
+        })
+      }
+    ],
+    isError: true
+  };
+}
+function makeDbConnectionErrorResponse() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "CATALOG_UNREACHABLE",
+          message: "Catalog database is unreachable. Verify your P58_DATABASE_URL is correct and the database server is accessible. If the problem persists, contact Tsvika.",
+          hint: "Check: (1) connection string starts with postgresql://mcp_friend... (2) port is 6543 (transaction pooler) (3) network allows outbound to AWS eu-north-1",
+          setup_guide: SETUP_GUIDE_URL
+        })
+      }
+    ],
+    isError: true
+  };
+}
+
 // dist/mcp/middleware/response-compression.js
 function selectFields(item, fields) {
   const result = {};
@@ -36684,8 +36819,11 @@ async function handleListOperations(args) {
     return toMCPResponse(response);
   } catch (error) {
     const originalError = error instanceof Error ? error : new Error(String(error));
-    const errorResponse = createInternalError(correlationId, originalError);
-    return toMCPResponse(errorResponse);
+    if (isDbConfigError(originalError))
+      return makeDbNotConfiguredResponse();
+    if (isDbConnectionError(originalError))
+      return makeDbConnectionErrorResponse();
+    return toMCPResponse(createInternalError(correlationId, originalError));
   }
 }
 var listOperationsToolDefinition = {
@@ -36782,13 +36920,16 @@ async function handleListNodes(args) {
     return toMCPResponse(response);
   } catch (error) {
     const originalError = error instanceof Error ? error : new Error(String(error));
-    const errorResponse = createInternalError(correlationId, originalError);
-    return toMCPResponse(errorResponse);
+    if (isDbConfigError(originalError))
+      return makeDbNotConfiguredResponse();
+    if (isDbConnectionError(originalError))
+      return makeDbConnectionErrorResponse();
+    return toMCPResponse(createInternalError(correlationId, originalError));
   }
 }
 var listNodesToolDefinition = {
   name: "list_nodes",
-  description: `List all available n8n nodes (1,982 total) with filtering and pagination.
+  description: `List all available n8n nodes (1,545 total) with filtering and pagination.
 
 Use this to discover available nodes before generating workflows. The tool supports:
 - Pagination: Use limit (1-100) and offset for large result sets
@@ -36945,8 +37086,11 @@ async function handleGetNodeInfo(args) {
     return toMCPResponse(response);
   } catch (error) {
     const originalError = error instanceof Error ? error : new Error(String(error));
-    const errorResponse = createInternalError(correlationId, originalError);
-    return toMCPResponse(errorResponse);
+    if (isDbConfigError(originalError))
+      return makeDbNotConfiguredResponse();
+    if (isDbConnectionError(originalError))
+      return makeDbConnectionErrorResponse();
+    return toMCPResponse(createInternalError(correlationId, originalError));
   }
 }
 var getNodeInfoToolDefinition = {
@@ -37034,8 +37178,11 @@ async function handleFindSimilarPattern(args) {
     return toMCPResponse(response);
   } catch (error) {
     const originalError = error instanceof Error ? error : new Error(String(error));
-    const errorResponse = createInternalError(correlationId, originalError);
-    return toMCPResponse(errorResponse);
+    if (isDbConfigError(originalError))
+      return makeDbNotConfiguredResponse();
+    if (isDbConnectionError(originalError))
+      return makeDbConnectionErrorResponse();
+    return toMCPResponse(createInternalError(correlationId, originalError));
   }
 }
 var findSimilarPatternToolDefinition = {
@@ -37232,8 +37379,8 @@ schemas, build_workflow handles validation, autofix, and deployment automaticall
 
 Runs L1-L4 validation before creating:
 - L1: JSON structure, required fields
-- L2: Node types exist in catalog (1,982 nodes)
-- L3: Credential types are valid (654 credentials)
+- L2: Node types exist in catalog (1,545 nodes)
+- L3: Credential types are valid (679 credentials)
 - L4: Connection patterns exist
 
 Refuses creation if any L1-L4 errors are found.
@@ -38604,7 +38751,7 @@ async function validateWorkflowObject(workflow, timeoutMs, label) {
 }
 async function runAutoFix(workflow, validationResult, timeoutMs, toolName) {
   const problems = validationResult.issues.filter((i) => i.severity === "error").map(issueToValidationProblem2);
-  const fixResult = await withTimeout(fixerRegistry.applyFixes(workflow, problems), timeoutMs, `${toolName} autofix`);
+  const fixResult = await withTimeout(getFixerRegistry().applyFixes(workflow, problems), timeoutMs, `${toolName} autofix`);
   return { fixedWorkflow: fixResult.workflow, fixResult };
 }
 async function applyAutoFixIfNeeded(workflow, validationResult, hasErrors, shouldFix, timeoutMs, correlationId, toolName) {
@@ -38825,6 +38972,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;
 }
@@ -39241,7 +39398,7 @@ function issueToValidationProblem3(issue) {
 }
 async function runFixStep(workflow, validation, timeoutMs) {
   const problems = validation.issues.filter((i) => i.severity === "error").map(issueToValidationProblem3);
-  const fixResult = await withTimeout(fixerRegistry.applyFixes(workflow, problems), timeoutMs, "server_autofix:fix");
+  const fixResult = await withTimeout(getFixerRegistry().applyFixes(workflow, problems), timeoutMs, "server_autofix:fix");
   return {
     fixedWorkflow: fixResult.workflow,
     fixes: extractAppliedFixes(fixResult)
@@ -41271,6 +41428,10 @@ and what service it connects to \u2014 don't attempt to build with a broken cred
 Part of the generation lifecycle: plan_workflow \u2192 test_credential(s) \u2192 build_workflow.
 NOT needed for editing or updating existing workflows (use update_workflow or partial_update_workflow).
 
+Note: plan_workflow works without n8n (catalog-only mode). To actually deploy
+workflows with build_workflow, N8N_API_KEY and N8N_API_URL must be configured.
+Without n8n, use plan_workflow for research and architecture planning only.
+
 Response modes:
 - "full": All research data within token_budget (default 8,000)
 - "summary" (default): Key fields within token_budget (default 4,000)
@@ -43077,7 +43238,12 @@ async function handleGetCredentialSchema(args) {
     return buildSchemaResponse(credential_type, rows, nodes, correlationId, startTime);
   } catch (error) {
     import_logging57.logger.error("get_credential_schema: unexpected error", { correlationId, error });
-    return toMCPResponse(createInternalError(correlationId, error instanceof Error ? error : new Error(String(error))));
+    const originalError = error instanceof Error ? error : new Error(String(error));
+    if (isDbConfigError(originalError))
+      return makeDbNotConfiguredResponse();
+    if (isDbConnectionError(originalError))
+      return makeDbConnectionErrorResponse();
+    return toMCPResponse(createInternalError(correlationId, originalError));
   }
 }
 async function handleUnknownType(credentialType, correlationId) {
@@ -44091,6 +44257,129 @@ When values are collected, marks matching factory.gaps entries as resolved for a
   }
 };
 
+// dist/mcp/tools/handlers/setup-check.js
+var SETUP_GUIDE_URL2 = "https://github.com/tsvika58/p58-n8n/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 = [
@@ -44127,7 +44416,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)) {
@@ -44155,13 +44445,21 @@ async function dispatchToolCall(name, args) {
   const tool = toolRegistry.get(name);
   if (!tool)
     return buildUnknownToolResponse(name);
-  if (tool.inputSchema && hasSchema(name)) {
-    const validation = validateToolInput(name, args);
-    if (!validation.success)
-      return createValidationErrorResponse(validation.error);
-    return tool.handler(validation.data);
+  if (requiresN8nApiKey(name) && !process.env.N8N_API_KEY) {
+    return makeN8nNotConfiguredError();
+  }
+  incrementInflight();
+  try {
+    if (tool.inputSchema && hasSchema(name)) {
+      const validation = validateToolInput(name, args);
+      if (!validation.success)
+        return createValidationErrorResponse(validation.error);
+      return await tool.handler(validation.data);
+    }
+    return await tool.handler(args);
+  } finally {
+    decrementInflight();
   }
-  return tool.handler(args);
 }
 async function handleToolCall(name, args, sessionId = "default") {
   const startTime = Date.now();
@@ -44179,7 +44477,9 @@ function registerAllTools() {
     registerTool({ ...entry, inputSchema: toolSchemas[entry.name] });
   }
 }
-registerAllTools();
+
+// dist/mcp/server.js
+init_validatorPostgresClient();
 
 // dist/mcp/middleware/credential-redaction.js
 var MAX_DEPTH = 20;
@@ -44352,6 +44652,7 @@ var defaultDeps = {
 };
 async function runCleanup(serverName, deps) {
   try {
+    await waitForInflightRequests(5e3);
     await deps.shutdownPool();
     deps.clearCache();
     deps.clearConfigCache?.();
@@ -44383,6 +44684,46 @@ function registerShutdownHandlers(serverName, deps) {
 }
 
 // dist/mcp/server.js
+var SETUP_GUIDE_URL3 = "https://github.com/tsvika58/p58-n8n/blob/main/docs/AGENT_INSTALL.md";
+var _serverInitialized = false;
+function isServerInitialized() {
+  return _serverInitialized;
+}
+function buildInitializingResponse() {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        error: "SERVER_INITIALIZING",
+        message: "Server is still loading. Please retry in a moment.",
+        retryAfterMs: 2e3
+      })
+    }],
+    isError: true
+  };
+}
+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 = OFFLINE_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
@@ -44405,6 +44746,9 @@ function toCallToolResult(response) {
 server.setRequestHandler(import_types22.CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
+    if (!_serverInitialized) {
+      return toCallToolResult(buildInitializingResponse());
+    }
     const response = await handleToolCall(name, args ?? {});
     return toCallToolResult(redactMCPResponse(response));
   } catch (error) {
@@ -44414,16 +44758,35 @@ server.setRequestHandler(import_types22.CallToolRequestSchema, async (request) =
 });
 async function main() {
   const transport = new import_stdio.StdioServerTransport();
+  const startMs = Date.now();
   await server.connect(transport);
+  console.error(`[INIT] MCP handshake complete in ${Date.now() - startMs}ms`);
+  registerAllTools();
+  _serverInitialized = true;
   const toolCount = getRegisteredTools().length;
-  console.error(`${config.SERVER_NAME} v${config.SERVER_VERSION} running on stdio (${toolCount} tools registered)`);
+  console.error(`[INIT] ${toolCount} tools registered in ${Date.now() - startMs}ms`);
+  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(() => {
+  });
+  if (process.env.P58_DATABASE_URL || process.env.MCP_DATABASE_URL) {
+    void warmValidatorPool().then(() => {
+      console.error("catalog: connected \u2713");
+    }).catch((err) => {
+      console.error(`catalog: WARNING \u2014 connection failed: ${err.message}`);
+      console.error("catalog: tools will retry on first use, but check P58_DATABASE_URL if errors persist");
+    });
+  }
 }
 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 = {
+  isServerInitialized,
+  logStartupSummary
+});
 /*! Bundled license information:
 
 mime-db/index.js:

package/package.json

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