@path58/p58-n8n 0.2.3 → 0.2.5

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

@@ -18436,7 +18436,6 @@ 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);
@@ -44561,22 +44560,12 @@ 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 tier1Count = OFFLINE_TOOLS.size;
   const tier27Count = totalTools - tier1Count;
   let n8nStatus;
   if (!apiKey) {
@@ -44639,7 +44628,6 @@ main().catch((error) => {
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TIER_1_TOOLS,
   logStartupSummary
 });
 /*! Bundled license information:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path58/p58-n8n",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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"