@path58/p58-n8n 0.2.10 → 0.2.12-rc.1

package/AGENT_INSTALL.md

@@ -99,6 +99,38 @@ The API key cannot be auto-discovered. The user must provide it or create one.
 
 ---
 
+## Step 3b: Get n8n Login Credentials (Optional — for credential testing)
+
+Some tools (`test_credential`, credential health checks) need REST session auth to access credential secrets. This requires the user's n8n login email and password.
+
+**When to ask:** If the user wants credential management features (testing, health audits), ask:
+> "To enable credential testing, I'll also need your n8n login email and password. These are the same credentials you use to log into the n8n web UI. Want to add them now?"
+
+**If the user declines:** Tier 2-7 tools still work — only `test_credential` will prompt for credentials per-call.
+
+**Security notes:**
+- These credentials are stored in the MCP config file alongside the API key (same security model)
+- The MCP server never logs credentials — they are only used to obtain a session cookie from n8n
+- The session cookie is ephemeral and not persisted to disk
+- If the user is uncomfortable storing their password in the config, they can omit it and provide credentials per-call when using `test_credential`
+
+**Advanced: Use a credential manager instead of plaintext:**
+
+If the user has 1Password CLI installed, they can reference secrets dynamically:
+```json
+{
+  "mcpServers": {
+    "p58-n8n": {
+      "command": "sh",
+      "args": ["-c", "N8N_API_KEY=$(op read 'op://Vault/n8n/api-key') N8N_USER_EMAIL=$(op read 'op://Vault/n8n/email') N8N_USER_PASSWORD=$(op read 'op://Vault/n8n/password') N8N_API_URL=http://localhost:5678/api/v1 npx -y @path58/p58-n8n"]
+    }
+  }
+}
+```
+This way no secrets are stored in the config file — they're fetched from 1Password at startup with biometric approval.
+
+---
+
 ## Step 4: Write the Configuration
 
 ### For Claude Desktop / Cursor / Gemini CLI / VS Code (JSON config)
@@ -114,7 +146,9 @@ Read the existing config file, then add p58-n8n inside the `mcpServers` object.
       "args": ["-y", "@path58/p58-n8n"],
       "env": {
         "N8N_API_URL": "http://localhost:5678/api/v1",
-        "N8N_API_KEY": "<paste-api-key-here>"
+        "N8N_API_KEY": "<paste-api-key-here>",
+        "N8N_USER_EMAIL": "<n8n-login-email>",
+        "N8N_USER_PASSWORD": "<n8n-login-password>"
       }
     }
   }
@@ -140,6 +174,8 @@ Read the existing config file, then add p58-n8n inside the `mcpServers` object.
 claude mcp add p58-n8n \
   -e N8N_API_URL=http://localhost:5678/api/v1 \
   -e N8N_API_KEY=<paste-api-key-here> \
+  -e N8N_USER_EMAIL=<n8n-login-email> \
+  -e N8N_USER_PASSWORD=<n8n-login-password> \
   -- npx -y @path58/p58-n8n
 ```
 
@@ -193,6 +229,8 @@ Ask: "List my n8n credentials"
 |----------|-----------|-------------|-------------|
 | `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 |
+| `N8N_USER_EMAIL` | For `test_credential` | n8n login email (REST session auth) | Same email you use to log into n8n UI |
+| `N8N_USER_PASSWORD` | For `test_credential` | n8n login password (REST session auth) | Same password you use to log into n8n UI |
 
 > **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`.
 
@@ -215,6 +253,7 @@ Ask: "List my n8n credentials"
 | "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 |
+| `test_credential` returns `NEEDS_N8N_LOGIN` | Session auth vars not set | Add `N8N_USER_EMAIL` and `N8N_USER_PASSWORD` to config (Step 3b) |
 | 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` |
 

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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).
 
+<<<<<<< HEAD
+## [0.2.11] - 2026-03-11
+
+### Added
+
+- **Session auth env vars** — `N8N_USER_EMAIL` and `N8N_USER_PASSWORD` now defined in env schema with Zod validation. When set in MCP config, `test_credential` works without per-call password prompts.
+- **Security documentation** — README now includes a full Security section documenting credential security model, auth layers, and user responsibilities.
+- **Credential helper example** — AGENT_INSTALL.md includes a 1Password CLI config pattern for users who prefer not to store passwords in plaintext config files.
+- **Step 3b in install guide** — AGENT_INSTALL.md now documents session auth setup as an optional step during installation.
+
 ## [0.2.10] - 2026-03-11
 
 ### Fixed

package/README.md

@@ -126,9 +126,9 @@ p58-n8n uses 80% less token context than n8n-mcp by serving structured catalog d
 
 ---
 
-## 35 Tools in 7 Tiers
+## 35 MCP Tools in 8 Categories
 
-### Tier 1 — Validation & Analysis
+### Schema & Node Intelligence
 
 | Tool | What it does |
 |------|-------------|
@@ -136,66 +136,71 @@ p58-n8n uses 80% less token context than n8n-mcp by serving structured catalog d
 | `get_operation_schema` | Exact parameter requirements for any node operation (ground truth, not LLM guesses) |
 | `check_parameter` | Real-time parameter validation — type checking, enum validation, typo detection |
 | `suggest_fix` | Concrete fix suggestions for validation issues — rename, add, remove, or replace |
-| `list_nodes` | Browse and search 1,545 n8n nodes by category or keyword |
+| `list_nodes` | Browse and search 1,982 n8n nodes by category or keyword |
 | `list_operations` | All operations for a node type, grouped by resource |
-| `get_node_info` | Full node details — operations, credentials, properties, version |
+| `get_node_info` | Full node details — operations, credentials, properties, config examples, version info |
 | `find_similar_pattern` | Search 10,003 real workflows for working examples |
 
-### Tier 2 — Server CRUD
+### Workflow CRUD
 
 | Tool | What it does |
 |------|-------------|
-| `get_workflow` | Fetch a workflow from your n8n instance by ID |
+| `create_workflow` | Create a workflow on your n8n server (L1-L4 validation gate) |
+| `get_workflow` | Fetch a deployed workflow by ID |
 | `list_workflows` | List all workflows with filtering and pagination |
-| `create_workflow` | Create a workflow on your n8n server |
 | `update_workflow` | Replace a workflow entirely |
-| `delete_workflow` | Delete a workflow (safe — checks for dependents) |
-| `execute_workflow` | Trigger workflow execution |
-| `get_execution_result` | Fetch the result of a completed execution |
+| `delete_workflow` | Delete a workflow (idempotent) |
+| `execute_workflow` | Trigger workflow execution (webhook, schedule, or manual) |
+| `get_execution_result` | Fetch execution details with per-node debug data |
 
-### Tier 3 — Advanced Operations
+### Smart Deploy
 
 | Tool | What it does |
 |------|-------------|
-| `validated_create` | Validate + deploy in one step — rejects invalid JSON before it hits your server |
-| `validated_update` | Validate + update in one step |
+| `validated_create` | Validate → autofix → auto-wire credentials → inject config → deploy atomically |
+| `validated_update` | Validate → autofix → update atomically |
 | `activate_workflow` | Toggle workflow active/inactive state |
-| `get_session_metrics` | Token usage and cost tracking for the current session |
 | `server_health` | Check your n8n instance connectivity and status |
+| `get_session_metrics` | Token usage and cost tracking for the current session |
 
-### Tier 4 — Tool Parity
+### Test & Iterate
 
 | Tool | What it does |
 |------|-------------|
-| `test_workflow` | Sandbox-test a workflow using K2 mock responses (no real credentials needed) |
-| `server_autofix` | Run all 35 auto-fixers on a workflow and return the repaired JSON |
-| `partial_update_workflow` | Diff-based partial updates — change one node without replacing the whole workflow |
-| `manage_executions` | List, filter, and delete workflow execution history |
-| `deploy_template` | Deploy a pre-built template from the workflow library |
+| `test_workflow` | Auto-detect trigger type and execute (respondToWebhook-aware, safe deactivation) |
+| `server_autofix` | Closed-loop: deploy → test → validate → fix → update → re-test (up to 10 iterations) |
+| `partial_update_workflow` | Diff-based surgical updates — 6 operations, atomic pre-validation |
+| `manage_executions` | List, get, or delete execution records with batch support |
+| `deploy_template` | Fetch and deploy a template from the public n8n template library |
 
-### Tier 5 — Workflow Generation
+### Workflow Generation
 
 | Tool | What it does |
 |------|-------------|
-| `plan_workflow` | Generate a structured workflow plan from a natural language description |
-| `build_workflow` | Build a complete workflow JSON from a plan — uses catalog data for correct parameters |
+| `plan_workflow` | Research templates, schemas, credentials, and architecture before building |
+| `build_workflow` | Assemble → validate → autofix → deploy → test from a structured spec |
 
-### Tier 6 — Credential Management
+### Credential Lifecycle
 
 | Tool | What it does |
 |------|-------------|
-| `list_credentials` | List n8n server credentials with optional schema enrichment |
+| `list_credentials` | List n8n server credentials with optional schema enrichment and node filtering |
 | `get_credential_schema` | Required and optional fields for any of 679 credential types (fuzzy match) |
-| `create_credential` | Create credentials with 5-step validation |
-| `test_credential` | Health-check probe — verifies connectivity for top credential types |
-| `update_credential` | Partial update — GET → merge → PATCH (preserves unmodified fields) |
+| `create_credential` | Schema-validated credential creation with duplicate detection |
+| `test_credential` | Health-check probe for 25 credential types (HTTP + TCP) |
+| `update_credential` | Rename a credential on the server |
 | `delete_credential` | Safe deletion with dependent workflow scan |
 
-### Tier 7 — Config Intelligence
+### Runtime Configuration
+
+| Tool | What it does |
+|------|-------------|
+| `collect_config` | Interactive config collection — spreadsheet IDs, webhook URLs, channel IDs, etc. |
+
+### Diagnostics
 
 | 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)
@@ -280,6 +285,49 @@ p58-n8n is in **soft launch** (friends & family). Issues and feedback welcome:
 
 ---
 
+## Security
+
+p58-n8n handles your n8n API keys, credentials, and server access. We take that responsibility seriously — here's exactly how your data is protected.
+
+### Your Data Stays on Your Machine
+
+p58-n8n runs as a **local stdio process**. There is no cloud relay, no telemetry, no external servers. Your credentials, workflow data, and n8n API traffic never leave your machine. The MCP protocol communicates exclusively via stdin/stdout with your local AI client.
+
+### Credential Security
+
+| Protection | How It Works |
+|-----------|-------------|
+| **No credential logging** | Passwords, API keys, and session tokens are never written to logs at any level — verified by automated grep checks |
+| **Ephemeral sessions** | n8n session cookies are created per-operation, held in memory only, and never persisted to disk |
+| **No secrets in responses** | MCP tool responses never include credential values — only metadata (name, type, health status) |
+| **Schema-validated config** | All environment variables are validated with Zod at startup — malformed values are rejected immediately |
+| **Fail-closed design** | Missing credentials produce clear error messages — the server never falls back to insecure defaults or guesses |
+| **Per-call override** | Users who prefer not to store passwords in config files can provide credentials per-tool-call instead |
+
+### Authentication Layers
+
+p58-n8n uses two independent auth mechanisms to talk to your n8n instance:
+
+| Layer | Variables | What It Accesses | When Needed |
+|-------|----------|-----------------|-------------|
+| **API Key** | `N8N_API_KEY` | Workflow CRUD, activation, execution | All Tier 2-7 tools |
+| **Session Auth** | `N8N_USER_EMAIL`, `N8N_USER_PASSWORD` | Credential secrets, credential testing | `test_credential` only |
+
+Session auth is **optional**. Without it, all tools work except `test_credential`, which will prompt for credentials per-call.
+
+### Your Responsibility
+
+While p58-n8n implements security best practices, **you are responsible for:**
+- Securing access to your n8n instance and API keys
+- Protecting your MCP config files (we recommend `chmod 600`)
+- Rotating API keys and passwords periodically
+- Using a credential manager (1Password, macOS Keychain) for production environments instead of plaintext config files
+- Reviewing what workflows the AI builds before deploying to production
+
+**We recommend:** Use a credential helper to inject secrets into your MCP config rather than storing them in plaintext. See [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for setup options.
+
+---
+
 ## Architecture
 
 p58-n8n runs as a local stdio MCP server. No cloud services required for basic use.