@path58/p58-n8n 0.2.3 → 0.2.4

package/AGENT_INSTALL.md

@@ -8,7 +8,7 @@
 
 ## What is p58-n8n?
 
-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:
+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:
 
 - **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
@@ -40,7 +40,7 @@ Determine which AI client the user is using. Check for config files in this orde
 | **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 |
+| **Gemini CLI** | `~/.gemini/settings.json` or `~/.gemini/antigravity/mcp_config.json` | All |
 | **VS Code (Copilot)** | `.vscode/mcp.json` in workspace | All |
 
 **Detection method:** Check if these files exist. If multiple exist, ask the user which client they want to configure.
@@ -101,7 +101,7 @@ The API key cannot be auto-discovered. The user must provide it or create one.
 
 ## Step 4: Write the Configuration
 
-### For Claude Desktop / Cursor / Windsurf / VS Code (JSON config)
+### 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.
 
@@ -159,7 +159,7 @@ The MCP server config is only read at startup. After writing the config:
 | **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 |
+| **Gemini CLI** | Exit and restart the CLI session, or use the MCP refresh command |
 
 **CRITICAL:** On macOS, closing the window is NOT enough for Claude Desktop. The user must Cmd+Q to fully quit.
 
@@ -232,4 +232,4 @@ Once installed, the user can ask their AI assistant to:
 
 ---
 
-**Package:** `@path58/p58-n8n` | **npm:** https://www.npmjs.com/package/@path58/p58-n8n | **Version:** 0.2.2+
+**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,11 +4,11 @@
 
 [![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/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.
+> **🤖 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.
 
 ---
 
@@ -58,9 +58,9 @@ Config file location: `~/Library/Application Support/Claude/claude_desktop_confi
 
 > **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.
+**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/n8n-workflow-validator/blob/main/AGENT_INSTALL.md) for the autonomous installation guide.
+**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
 
@@ -126,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
 
@@ -196,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)
 
@@ -235,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
 
@@ -274,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
 
 ---
@@ -284,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

@@ -3014,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}`);
@@ -3041,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) => {
@@ -3062,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";
@@ -3077,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;
   }
 });
 
@@ -18436,7 +18461,7 @@ var init_cached_catalog_adapter = __esm({
 // dist/mcp/server.js
 var server_exports = {};
 __export(server_exports, {
-  TIER_1_TOOLS: () => TIER_1_TOOLS,
+  isServerInitialized: () => isServerInitialized,
   logStartupSummary: () => logStartupSummary
 });
 module.exports = __toCommonJS(server_exports);
@@ -18448,7 +18473,7 @@ var import_types22 = require("@modelcontextprotocol/sdk/types.js");
 var config = {
   // Server identity
   SERVER_NAME: "p58-n8n",
-  SERVER_VERSION: "0.2.3",
+  SERVER_VERSION: "0.2.4",
   // Database configuration (from environment)
   SUPABASE_URL: process.env.SUPABASE_URL,
   SUPABASE_KEY: process.env.SUPABASE_KEY,
@@ -19180,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();
@@ -30389,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) {
@@ -34887,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,
@@ -35282,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.
@@ -35488,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:
@@ -36574,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 = {};
@@ -36693,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 = {
@@ -36791,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
@@ -36954,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 = {
@@ -37043,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 = {
@@ -37241,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.
@@ -38613,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) {
@@ -39260,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)
@@ -41290,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)
@@ -43096,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) {
@@ -44110,40 +44257,8 @@ 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 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) {
@@ -44333,13 +44448,18 @@ async function dispatchToolCall(name, args) {
   if (requiresN8nApiKey(name) && !process.env.N8N_API_KEY) {
     return makeN8nNotConfiguredError();
   }
-  if (tool.inputSchema && hasSchema(name)) {
-    const validation = validateToolInput(name, args);
-    if (!validation.success)
-      return createValidationErrorResponse(validation.error);
-    return tool.handler(validation.data);
+  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();
@@ -44357,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;
@@ -44530,6 +44652,7 @@ var defaultDeps = {
 };
 async function runCleanup(serverName, deps) {
   try {
+    await waitForInflightRequests(5e3);
     await deps.shutdownPool();
     deps.clearCache();
     deps.clearConfigCache?.();
@@ -44561,22 +44684,29 @@ 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";
+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 = TIER_1_TOOLS.size;
+  const tier1Count = OFFLINE_TOOLS.size;
   const tier27Count = totalTools - tier1Count;
   let n8nStatus;
   if (!apiKey) {
@@ -44616,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) {
@@ -44625,13 +44758,25 @@ 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);
   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);
@@ -44639,7 +44784,7 @@ main().catch((error) => {
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TIER_1_TOOLS,
+  isServerInitialized,
   logStartupSummary
 });
 /*! Bundled license information:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path58/p58-n8n",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "The smartest and fastest n8n MCP server — validate, fix, and discover workflows inside your LLM",
   "keywords": [
     "mcp",
@@ -13,10 +13,10 @@
   ],
   "author": "Path58",
   "license": "MIT",
-  "homepage": "https://github.com/tsvika58/n8n-workflow-validator#readme",
+  "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"