chore: import upstream snapshot with attribution

.github/workflows/dependency-check.yml

@@ -0,0 +1,225 @@
+name: Dependency Compatibility Check
+
+# This workflow verifies that when users install n8n-mcp via npm (without lockfile),
+# they get compatible dependency versions. This catches issues like #440, #444, #446, #447, #450
+# where npm resolution gave users incompatible SDK/Zod versions.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/dependency-check.yml'
+  # Allow manual trigger for debugging
+  workflow_dispatch:
+  # Run weekly to catch upstream dependency changes
+  schedule:
+    - cron: '0 6 * * 1'  # Every Monday at 6 AM UTC
+
+permissions:
+  contents: read
+
+jobs:
+  fresh-install-check:
+    name: Fresh Install Dependency Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - name: Build package
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: |
+          npm ci --legacy-peer-deps
+          npm run build
+
+      - name: Pack package for testing
+        run: npm pack
+
+      - name: Create fresh install test directory
+        run: |
+          mkdir -p /tmp/fresh-install-test
+          cp n8n-mcp-*.tgz /tmp/fresh-install-test/
+
+      - name: Install package fresh (simulating user install)
+        working-directory: /tmp/fresh-install-test
+        run: |
+          npm init -y
+          # Install from tarball WITHOUT lockfile (simulates npm install n8n-mcp)
+          # Use --ignore-scripts to skip native compilation of transitive deps like isolated-vm
+          # (n8n-mcp only reads node metadata, it doesn't execute n8n nodes at runtime)
+          npm install --ignore-scripts ./n8n-mcp-*.tgz
+
+      - name: Verify critical dependency versions
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Dependency Version Check ==="
+          echo ""
+
+          # Get actual resolved versions
+          SDK_VERSION=$(npm list @modelcontextprotocol/sdk --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies["@modelcontextprotocol/sdk"].version // .dependencies["@modelcontextprotocol/sdk"].version // "not found"')
+          ZOD_VERSION=$(npm list zod --json 2>/dev/null | jq -r '.dependencies["n8n-mcp"].dependencies.zod.version // .dependencies.zod.version // "not found"')
+
+          echo "MCP SDK version: $SDK_VERSION"
+          echo "Zod version: $ZOD_VERSION"
+          echo ""
+
+          # Check MCP SDK version - must be exactly 1.28.0
+          if [[ "$SDK_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine MCP SDK version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$SDK_VERSION" != "1.28.0" ]]; then
+            echo "❌ FAILED: MCP SDK version mismatch!"
+            echo "   Expected: 1.28.0"
+            echo "   Got: $SDK_VERSION"
+            echo ""
+            echo "This can cause runtime errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ MCP SDK version is correct: $SDK_VERSION"
+
+          # Check Zod version - must be 3.x (not 4.x, including pre-releases)
+          if [[ "$ZOD_VERSION" == "not found" ]]; then
+            echo "❌ FAILED: Could not determine Zod version!"
+            echo "   The dependency may not have been installed correctly."
+            exit 1
+          fi
+          if [[ "$ZOD_VERSION" =~ ^4\. ]]; then
+            echo "❌ FAILED: Zod v4 detected - incompatible with MCP SDK 1.27.1!"
+            echo "   Expected: 3.x"
+            echo "   Got: $ZOD_VERSION"
+            echo ""
+            echo "Zod v4 causes '_zod' property errors. See issues #440, #444, #446, #447, #450"
+            exit 1
+          fi
+          echo "✅ Zod version is compatible: $ZOD_VERSION"
+
+          echo ""
+          echo "=== All dependency checks passed ==="
+
+      - name: Test basic functionality
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Basic Functionality Test ==="
+
+          # Create a simple test script
+          cat > test-import.mjs << 'EOF'
+          import { spawn } from 'child_process';
+          import path from 'path';
+          import { fileURLToPath } from 'url';
+
+          const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+          // Test that the package can be required and basic tools work
+          async function test() {
+            console.log('Testing n8n-mcp package import...');
+
+            // Start the MCP server briefly to verify it initializes
+            const serverPath = path.join(__dirname, 'node_modules/n8n-mcp/dist/mcp/index.js');
+
+            const proc = spawn('node', [serverPath], {
+              env: { ...process.env, MCP_MODE: 'stdio' },
+              stdio: ['pipe', 'pipe', 'pipe']
+            });
+
+            // Send initialize request
+            const initRequest = JSON.stringify({
+              jsonrpc: '2.0',
+              id: 1,
+              method: 'initialize',
+              params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'test', version: '1.0.0' }
+              }
+            });
+
+            proc.stdin.write(initRequest + '\n');
+
+            // Wait for response or timeout
+            let output = '';
+            let stderrOutput = '';
+            proc.stdout.on('data', (data) => {
+              output += data.toString();
+            });
+
+            proc.stderr.on('data', (data) => {
+              stderrOutput += data.toString();
+              console.error('stderr:', data.toString());
+            });
+
+            // Give it 5 seconds to respond
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+
+            proc.kill();
+
+            // Check for Zod v4 compatibility errors (the bug we're testing for)
+            const allOutput = output + stderrOutput;
+            if (allOutput.includes('_zod') || allOutput.includes('Cannot read properties of undefined')) {
+              console.error('❌ FAILED: Zod compatibility error detected!');
+              console.error('This indicates the SDK/Zod version fix is not working.');
+              console.error('See issues #440, #444, #446, #447, #450');
+              process.exit(1);
+            }
+
+            if (output.includes('"result"')) {
+              console.log('✅ MCP server initialized successfully');
+              return true;
+            } else {
+              console.log('Output received:', output.substring(0, 500));
+              // Server might not respond in stdio mode without proper framing
+              // But if we got here without crashing, that's still good
+              console.log('✅ MCP server started without errors');
+              return true;
+            }
+          }
+
+          test()
+            .then(() => {
+              console.log('=== Basic functionality test passed ===');
+              process.exit(0);
+            })
+            .catch((err) => {
+              console.error('❌ Test failed:', err.message);
+              process.exit(1);
+            });
+          EOF
+
+          node test-import.mjs
+
+      - name: Generate dependency report
+        if: always()
+        working-directory: /tmp/fresh-install-test
+        run: |
+          echo "=== Full Dependency Tree ===" > dependency-report.txt
+          npm list --all >> dependency-report.txt 2>&1 || true
+
+          echo "" >> dependency-report.txt
+          echo "=== Critical Dependencies ===" >> dependency-report.txt
+          npm list @modelcontextprotocol/sdk zod zod-to-json-schema >> dependency-report.txt 2>&1 || true
+
+          cat dependency-report.txt
+
+      - name: Upload dependency report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: dependency-report-${{ github.run_number }}
+          path: /tmp/fresh-install-test/dependency-report.txt
+          retention-days: 30

.github/workflows/docker-build-fast.yml

@@ -0,0 +1,68 @@
+# .github/workflows/docker-build-fast.yml
+name: Build Docker (AMD64 only - Fast)
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'Dockerfile'
+      - 'package.runtime.json'
+      - '.github/workflows/docker-build-fast.yml'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-amd64:
+    name: Build Docker Image (AMD64 only)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+        
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=pr,suffix=-amd64
+            type=raw,value=test-amd64
+            
+      - name: Build and push Docker image (AMD64 only)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false

.github/workflows/docker-build-n8n.yml

@@ -0,0 +1,188 @@
+name: Build and Publish n8n Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/n8n-mcp
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+  test-image:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test Docker image
+        run: |
+          # Test that the image starts correctly with N8N_MODE
+          docker run --rm \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest \
+            node -e "console.log('N8N_MODE:', process.env.N8N_MODE); process.exit(0);"
+
+      - name: Test health endpoint
+        run: |
+          # Start container in background
+          docker run -d \
+            --name n8n-mcp-test \
+            -p 3000:3000 \
+            -e N8N_MODE=true \
+            -e MCP_MODE=http \
+            -e N8N_API_URL=http://localhost:5678 \
+            -e N8N_API_KEY=test \
+            -e MCP_AUTH_TOKEN=test-token-minimum-32-chars-long \
+            -e AUTH_TOKEN=test-token-minimum-32-chars-long \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          
+          # Wait for container to start
+          sleep 10
+          
+          # Test health endpoint
+          curl -f http://localhost:3000/health || exit 1
+          
+          # Test MCP endpoint (requires auth since v2.47.6)
+          curl -f -H "Authorization: Bearer test-token-minimum-32-chars-long" http://localhost:3000/mcp || exit 1
+          
+          # Cleanup
+          docker stop n8n-mcp-test
+          docker rm n8n-mcp-test
+
+  create-release:
+    needs: [build-and-push, test-image]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          body: |
+            ## Docker Image
+
+            The n8n-specific Docker image is available at:
+            ```
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
+            ```
+
+            ## Quick Deploy
+
+            Use the quick deploy script for easy setup:
+            ```bash
+            ./deploy/quick-deploy-n8n.sh setup
+            ```
+
+            See the [deployment documentation](https://github.com/${{ github.repository }}/blob/main/docs/deployment-n8n.md) for detailed instructions.

.github/workflows/docker-build.yml

@@ -0,0 +1,237 @@
+# .github/workflows/docker-build.yml
+name: Build and Push Docker Images
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  workflow_dispatch:
+
+# Prevent concurrent Docker pushes across all workflows (shared with release.yml)
+# This ensures docker-build.yml and release.yml never push to 'latest' simultaneously
+concurrency:
+  group: docker-push-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+
+      - name: Sync runtime version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          no-cache: false
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+
+      - name: Verify multi-arch manifest for latest tag
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        run: |
+          echo "Verifying multi-arch manifest for latest tag..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+  build-railway:
+    name: Build Railway Docker Image
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+
+      - name: Sync runtime version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Extract metadata for Railway
+        id: meta-railway
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+            
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          no-cache: false
+          platforms: linux/amd64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+
+  # Nginx build commented out until Phase 2
+  # build-nginx:
+  #   name: Build nginx-enhanced Docker Image
+  #   runs-on: ubuntu-latest
+  #   permissions:
+  #     contents: read
+  #     packages: write

.github/workflows/issue-triage.md

@@ -0,0 +1,101 @@
+---
+description: |
+  Intelligent issue triage assistant that processes new and reopened issues.
+  Analyzes issue content, selects appropriate labels, detects spam, gathers context
+  from similar issues, and provides analysis notes including debugging strategies,
+  reproduction steps, and resource links. Helps maintainers quickly understand and
+  prioritize incoming issues.
+
+on:
+  roles: all
+  issues:
+    types: [opened, reopened]
+  skip-bots: [dependabot, github-actions, copilot]
+  reaction: eyes
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+network: defaults
+
+safe-outputs:
+  environment: agentic-triage-passthrough
+  report-failure-as-issue: false
+  add-labels:
+    max: 5
+  add-comment:
+  noop:
+    report-as-issue: false
+  missing-tool:
+    create-issue: false
+  report-incomplete:
+    create-issue: false
+  missing-data:
+    create-issue: false
+
+tools:
+  github:
+    toolsets: [issues]
+    read-only: true
+    min-integrity: none # Allow this workflow to examine issues from any author. The MCP server is read-only; comments and labels are written via the safe-outputs channel.
+
+environment: agentic-triage
+
+timeout-minutes: 10
+source: githubnext/agentics/workflows/issue-triage.md@13377ddf7e35c2b6e47aa58f45acb228fba902c8
+---
+
+# Agentic Triage
+
+<!-- Note - this file can be customized to your needs. Replace this section directly, or add further instructions here. After editing run 'gh aw compile' -->
+
+You're a triage assistant for GitHub issues. Your task is to analyze issue #${{ github.event.issue.number }} and perform some initial triage tasks related to that issue. Follow the steps below in order.
+
+1. Retrieve the issue content using the `get_issue` tool. If the issue is obviously spam, or generated by bot, or something else that is not an actual issue to be worked on, emit a one-sentence analysis via the `add_comment` safe-output and exit the workflow. Do not call `update_issue` or any other GitHub write tool — the MCP server is read-only and those calls will be blocked.
+
+2. Next, use the GitHub tools to gather additional context about the issue:
+
+   - Fetch the list of labels available in this repository using the `list_labels` tool. This will give you the labels you can use for triaging issues.
+   - Fetch any comments on the issue using the `get_issue_comments` tool
+   - Find similar issues if needed using the `search_issues` tool
+   - List the issues to see other open issues in the repository using the `list_issues` tool
+
+3. Analyze the issue content, considering:
+
+   - The issue title and description
+   - The type of issue (bug report, feature request, question, etc.)
+   - Technical areas mentioned
+   - Severity or priority indicators
+   - User impact
+   - Components affected
+
+4. Write notes, ideas, nudges, resource links, debugging strategies and/or reproduction steps for the team to consider relevant to the issue.
+
+5. Select appropriate labels from the available labels list provided above:
+
+   - Choose labels that accurately reflect the issue's nature
+   - Be specific but comprehensive
+   - Select priority labels if you can determine urgency (high-priority, med-priority, or low-priority)
+   - Consider platform labels (android, ios) if applicable
+   - Search for similar issues, and if you find similar issues consider using a "duplicate" label if appropriate. Only do so if the issue is a duplicate of another OPEN issue.
+   - Only select labels from the provided list above
+   - It's okay to not add any labels if none are clearly applicable
+
+6. Apply the selected labels:
+
+   - Emit the labels via the `add_labels` safe-output. The GitHub MCP server is read-only; do not attempt `update_issue` — it will be blocked and the labels will not be applied.
+   - If no labels are clearly applicable, do not emit any
+
+7. Emit your analysis via the `add_comment` safe-output (the GitHub MCP server is read-only — do not attempt `update_issue` or any direct comment write). The comment is addressed to maintainers reading the issue, not to the reporter — do not ask the reporter for follow-ups, request information, or otherwise direct them to do anything. Use neutral third-person phrasing.
+   - Start with "🎯 Agentic Issue Triage"
+   - Provide a brief summary of the issue
+   - Mention any relevant details that might help the team understand the issue better
+   - Include any debugging strategies or reproduction steps if applicable
+   - Suggest resources or links that might be helpful for resolving the issue or learning skills related to the issue or the particular area of the codebase affected by it
+   - Mention any nudges or ideas that could help the team in addressing the issue
+   - If you have possible reproduction steps, include them in the comment
+   - If you have any debugging strategies, include them in the comment
+   - If appropriate break the issue down to sub-tasks and write a checklist of things to do.
+   - Use collapsed-by-default sections in the GitHub markdown to keep the comment tidy. Collapse all sections except the short main summary at the top.

.github/workflows/release.yml

@@ -0,0 +1,729 @@
+name: Automated Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package.runtime.json'
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  pull-requests: write
+
+# Prevent concurrent Docker pushes across all workflows (shared with docker-build.yml)
+# This ensures release.yml and docker-build.yml never push to 'latest' simultaneously
+concurrency:
+  group: docker-push-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  detect-version-change:
+    name: Detect Version Change
+    runs-on: ubuntu-latest
+    outputs:
+      version-changed: ${{ steps.check.outputs.changed }}
+      new-version: ${{ steps.check.outputs.version }}
+      previous-version: ${{ steps.check.outputs.previous-version }}
+      is-prerelease: ${{ steps.check.outputs.is-prerelease }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 2
+      
+      - name: Check for version change
+        id: check
+        run: |
+          # Get current version from package.json
+          CURRENT_VERSION=$(node -e "console.log(require('./package.json').version)")
+          
+          # Get previous version from git history safely
+          PREVIOUS_VERSION=$(git show HEAD~1:package.json 2>/dev/null | node -e "
+            try {
+              const data = require('fs').readFileSync(0, 'utf8');
+              const pkg = JSON.parse(data);
+              console.log(pkg.version || '0.0.0');
+            } catch (e) {
+              console.log('0.0.0');
+            }
+          " || echo "0.0.0")
+          
+          echo "Previous version: $PREVIOUS_VERSION"
+          echo "Current version: $CURRENT_VERSION"
+          
+          # Check if version changed
+          if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            
+            # Check if it's a prerelease (contains alpha, beta, rc, dev)
+            if echo "$CURRENT_VERSION" | grep -E "(alpha|beta|rc|dev)" > /dev/null; then
+              echo "is-prerelease=true" >> $GITHUB_OUTPUT
+            else
+              echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            fi
+            
+            echo "🎉 Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "previous-version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
+            echo "is-prerelease=false" >> $GITHUB_OUTPUT
+            echo "ℹ️ No version change detected"
+          fi
+
+      - name: Validate version against npm registry
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          CURRENT_VERSION="${{ steps.check.outputs.version }}"
+
+          # Get latest version from npm (handle package not found)
+          NPM_VERSION=$(npm view n8n-mcp version 2>/dev/null || echo "0.0.0")
+
+          echo "Current version: $CURRENT_VERSION"
+          echo "NPM registry version: $NPM_VERSION"
+
+          # Check if version already exists in npm
+          if [ "$CURRENT_VERSION" = "$NPM_VERSION" ]; then
+            echo "❌ Error: Version $CURRENT_VERSION already published to npm"
+            echo "Please bump the version in package.json before releasing"
+            exit 1
+          fi
+
+          # Simple semver comparison (assumes format: major.minor.patch)
+          # Compare if current version is greater than npm version
+          if [ "$NPM_VERSION" != "0.0.0" ]; then
+            # Sort versions and check if current is not the highest
+            HIGHEST=$(printf '%s\n%s' "$NPM_VERSION" "$CURRENT_VERSION" | sort -V | tail -n1)
+            if [ "$HIGHEST" != "$CURRENT_VERSION" ]; then
+              echo "❌ Error: Version $CURRENT_VERSION is not greater than npm version $NPM_VERSION"
+              echo "Please use a higher version number"
+              exit 1
+            fi
+          fi
+
+          echo "✅ Version $CURRENT_VERSION is valid (higher than npm version $NPM_VERSION)"
+
+  generate-release-notes:
+    name: Generate Release Notes
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-notes: ${{ steps.generate.outputs.notes }}
+      has-notes: ${{ steps.generate.outputs.has-notes }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # Need full history for git log
+
+      - name: Generate release notes from commits
+        id: generate
+        run: |
+          CURRENT_VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          CURRENT_TAG="v$CURRENT_VERSION"
+
+          # Get the previous tag (excluding the current tag which doesn't exist yet)
+          PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -v "^$CURRENT_TAG$" | head -1)
+
+          echo "Current version: $CURRENT_VERSION"
+          echo "Current tag: $CURRENT_TAG"
+          echo "Previous tag: $PREVIOUS_TAG"
+
+          if [ -z "$PREVIOUS_TAG" ]; then
+            echo "ℹ️ No previous tag found, this might be the first release"
+
+            # Generate initial release notes using script
+            if NOTES=$(node scripts/generate-initial-release-notes.js "$CURRENT_VERSION" 2>/dev/null); then
+              echo "✅ Successfully generated initial release notes for version $CURRENT_VERSION"
+            else
+              echo "⚠️ Could not generate initial release notes for version $CURRENT_VERSION"
+              NOTES="Initial release v$CURRENT_VERSION"
+            fi
+
+            echo "has-notes=true" >> $GITHUB_OUTPUT
+
+            # Use heredoc to properly handle multiline content
+            {
+              echo "notes<<EOF"
+              echo "$NOTES"
+              echo "EOF"
+            } >> $GITHUB_OUTPUT
+
+          else
+            echo "✅ Previous tag found: $PREVIOUS_TAG"
+
+            # Generate release notes between tags
+            if NOTES=$(node scripts/generate-release-notes.js "$PREVIOUS_TAG" "HEAD" 2>/dev/null); then
+              echo "has-notes=true" >> $GITHUB_OUTPUT
+
+              # Use heredoc to properly handle multiline content
+              {
+                echo "notes<<EOF"
+                echo "$NOTES"
+                echo "EOF"
+              } >> $GITHUB_OUTPUT
+
+              echo "✅ Successfully generated release notes from $PREVIOUS_TAG to $CURRENT_TAG"
+            else
+              echo "has-notes=false" >> $GITHUB_OUTPUT
+              echo "notes=Failed to generate release notes for version $CURRENT_VERSION" >> $GITHUB_OUTPUT
+              echo "⚠️ Could not generate release notes for version $CURRENT_VERSION"
+            fi
+          fi
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, generate-release-notes]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    outputs:
+      release-id: ${{ steps.create.outputs.id }}
+      upload-url: ${{ steps.create.outputs.upload_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+      
+      - name: Create Git Tag
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Create annotated tag
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"
+      
+      - name: Create GitHub Release
+        id: create
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          IS_PRERELEASE="${{ needs.detect-version-change.outputs.is-prerelease }}"
+          
+          # Create release body
+          cat > release_body.md << 'EOF'
+          # Release v${{ needs.detect-version-change.outputs.new-version }}
+          
+          ${{ needs.generate-release-notes.outputs.release-notes }}
+          
+          ---
+          
+          ## Installation
+          
+          ### NPM Package
+          ```bash
+          # Install globally
+          npm install -g n8n-mcp
+          
+          # Or run directly
+          npx n8n-mcp
+          ```
+          
+          ### Docker
+          ```bash
+          # Standard image
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v${{ needs.detect-version-change.outputs.new-version }}
+          
+          # Railway optimized
+          docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp-railway:v${{ needs.detect-version-change.outputs.new-version }}
+          ```
+          
+          ## Documentation
+          - [Installation Guide](https://github.com/czlonkowski/n8n-mcp#installation)
+          - [Docker Deployment](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/DOCKER_README.md)
+          - [n8n Integration](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md)
+          - [Complete Changelog](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CHANGELOG.md)
+          
+          🤖 *Generated with [Claude Code](https://claude.ai/code)*
+          EOF
+          
+          # Create release using gh CLI
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          else
+            PRERELEASE_FLAG=""
+          fi
+          
+          gh release create "v$VERSION" \
+            --title "Release v$VERSION" \
+            --notes-file release_body.md \
+            $PRERELEASE_FLAG
+          
+          # Output release info for next jobs
+          RELEASE_ID=$(gh release view "v$VERSION" --json id --jq '.id')
+          echo "id=$RELEASE_ID" >> $GITHUB_OUTPUT
+          echo "upload_url=https://uploads.github.com/repos/${{ github.repository }}/releases/$RELEASE_ID/assets{?name,label}" >> $GITHUB_OUTPUT
+
+  package-mcpb:
+    name: Package MCPB Bundle
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      # Build so dist/mcp/index.js exists at pack time: `mcpb pack` runs existsSync
+      # on the manifest entry_point against the source dir, and dist/ is gitignored.
+      - name: Build project
+        run: npm run build
+
+      - name: Generate MCPB manifest from package.json + tool registry
+        run: npm run generate:mcpb-manifest
+
+      - name: Validate and pack MCPB bundle
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          npx -y @anthropic-ai/mcpb validate manifest.json
+          npx -y @anthropic-ai/mcpb pack . "n8n-mcp-${VERSION}.mcpb"
+
+      - name: Upload MCPB bundle to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          gh release upload "v$VERSION" "n8n-mcp-${VERSION}.mcpb" --clobber
+
+  build-and-verify:
+    name: Build and Verify
+    runs-on: ubuntu-latest
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      - name: Build project (server + UI apps)
+        run: npm run build:all
+
+      # Database is already built and committed during development
+      # Rebuilding here causes segfault due to memory pressure (exit code 139)
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            echo "Please run 'npm run rebuild' locally and commit the database"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
+      # Skip tests - they already passed in PR before merge
+      # Running them again on the same commit adds no safety, only time (~6-7 min)
+
+      - name: Run type checking
+        run: npm run typecheck
+
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-verify, create-release]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Upgrade npm to >= 11.5.1 (Trusted Publisher support)
+        run: |
+          npm install -g 'npm@^11.5.1'
+          npm --version
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --legacy-peer-deps
+
+      - name: Build project (server + UI apps)
+        run: npm run build:all
+
+      # Database is already built and committed during development
+      - name: Verify database exists
+        run: |
+          if [ ! -f "data/nodes.db" ]; then
+            echo "❌ Error: data/nodes.db not found"
+            exit 1
+          fi
+          echo "✅ Database exists ($(du -h data/nodes.db | cut -f1))"
+
+      - name: Sync runtime version
+        run: npm run sync:runtime-version
+      
+      - name: Prepare package for publishing
+        run: |
+          # Create publish directory
+          PUBLISH_DIR="npm-publish-temp"
+          rm -rf $PUBLISH_DIR
+          mkdir -p $PUBLISH_DIR
+          
+          # Copy necessary files
+          cp -r dist $PUBLISH_DIR/
+          cp -r data $PUBLISH_DIR/
+          mkdir -p $PUBLISH_DIR/ui-apps
+          cp -r ui-apps/dist $PUBLISH_DIR/ui-apps/
+          cp README.md $PUBLISH_DIR/
+          cp LICENSE $PUBLISH_DIR/
+          cp .env.example $PUBLISH_DIR/
+          
+          # Use runtime package.json as base
+          cp package.runtime.json $PUBLISH_DIR/package.json
+          
+          cd $PUBLISH_DIR
+          
+          # Update package.json with complete metadata
+          node -e "
+          const pkg = require('./package.json');
+          pkg.name = 'n8n-mcp';
+          pkg.description = 'Integration between n8n workflow automation and Model Context Protocol (MCP)';
+          pkg.main = 'dist/index.js';
+          pkg.types = 'dist/index.d.ts';
+          pkg.exports = {
+            '.': {
+              types: './dist/index.d.ts',
+              require: './dist/index.js',
+              import: './dist/index.js'
+            }
+          };
+          pkg.bin = { 'n8n-mcp': './dist/mcp/stdio-wrapper.js' };
+          pkg.repository = { type: 'git', url: 'git+https://github.com/czlonkowski/n8n-mcp.git' };
+          pkg.keywords = ['n8n', 'mcp', 'model-context-protocol', 'ai', 'workflow', 'automation'];
+          pkg.author = 'Romuald Czlonkowski @ www.aiadvisors.pl/en';
+          pkg.license = 'MIT';
+          pkg.bugs = { url: 'https://github.com/czlonkowski/n8n-mcp/issues' };
+          pkg.homepage = 'https://github.com/czlonkowski/n8n-mcp#readme';
+          pkg.files = ['dist/**/*', 'ui-apps/dist/**/*', 'data/nodes.db', '.env.example', 'README.md', 'LICENSE'];
+          delete pkg.private;
+          require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
+          "
+          
+          echo "Package prepared for publishing:"
+          echo "Name: $(node -e "console.log(require('./package.json').name)")"
+          echo "Version: $(node -e "console.log(require('./package.json').version)")"
+      
+      - name: Publish to NPM with retry
+        uses: nick-invision/retry@v4
+        with:
+          timeout_minutes: 5
+          max_attempts: 3
+          command: |
+            cd npm-publish-temp
+            npm publish --access public --provenance
+
+      - name: Clean up
+        if: always()
+        run: rm -rf npm-publish-temp
+
+  build-docker:
+    name: Build and Push Docker Images
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, build-and-verify]
+    if: needs.detect-version-change.outputs.version-changed == 'true'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          lfs: true
+      
+      - name: Check disk space
+        run: |
+          echo "Disk usage before Docker build:"
+          df -h
+          
+          # Check available space (require at least 2GB)
+          AVAILABLE_GB=$(df / --output=avail --block-size=1G | tail -1)
+          if [ "$AVAILABLE_GB" -lt 2 ]; then
+            echo "❌ Insufficient disk space: ${AVAILABLE_GB}GB available, 2GB required"
+            exit 1
+          fi
+          echo "✅ Sufficient disk space: ${AVAILABLE_GB}GB available"
+
+      - name: Sync runtime version for Docker
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.runtime.json'));
+            pkg.version = '$VERSION';
+            fs.writeFileSync('package.runtime.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+          echo "✅ Synced package.runtime.json to version $VERSION"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Extract metadata for standard image
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push standard Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Verify multi-arch manifest for latest tag
+        run: |
+          echo "Verifying multi-arch manifest for latest tag..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+      - name: Verify multi-arch manifest for version tag
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          echo "Verifying multi-arch manifest for version tag :$VERSION (without 'v' prefix)..."
+
+          # Retry with exponential backoff (registry propagation can take time)
+          MAX_ATTEMPTS=5
+          ATTEMPT=1
+          WAIT_TIME=2
+
+          while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
+            echo "Attempt $ATTEMPT of $MAX_ATTEMPTS..."
+
+            MANIFEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$VERSION 2>&1 || true)
+
+            # Check for both platforms
+            if echo "$MANIFEST" | grep -q "linux/amd64" && echo "$MANIFEST" | grep -q "linux/arm64"; then
+              echo "✅ Multi-arch manifest verified for $VERSION: both amd64 and arm64 present"
+              echo "$MANIFEST"
+              exit 0
+            fi
+
+            if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+              echo "⏳ Registry still propagating, waiting ${WAIT_TIME}s before retry..."
+              sleep $WAIT_TIME
+              WAIT_TIME=$((WAIT_TIME * 2))  # Exponential backoff: 2s, 4s, 8s, 16s
+            fi
+
+            ATTEMPT=$((ATTEMPT + 1))
+          done
+
+          echo "❌ ERROR: Multi-arch manifest incomplete for version $VERSION after $MAX_ATTEMPTS attempts!"
+          echo "$MANIFEST"
+          exit 1
+
+      - name: Extract metadata for Railway image
+        id: meta-railway
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=semver,pattern={{major}},value=v${{ needs.detect-version-change.outputs.new-version }}
+            type=raw,value=latest,enable={{is_default_branch}}
+      
+      - name: Build and push Railway Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile.railway
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta-railway.outputs.tags }}
+          labels: ${{ steps.meta-railway.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  update-documentation:
+    name: Update Documentation
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker]
+    if: needs.detect-version-change.outputs.version-changed == 'true' && !failure()
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+      
+      - name: Update version badges in README
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          
+          # Update README version badges
+          if [ -f "README.md" ]; then
+            # Update npm version badge
+            sed -i.bak "s|npm/v/n8n-mcp/[^)]*|npm/v/n8n-mcp/$VERSION|g" README.md
+            
+            # Update any other version references
+            sed -i.bak "s|version-[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*|version-$VERSION|g" README.md
+            
+            # Clean up backup file
+            rm -f README.md.bak
+            
+            echo "✅ Updated version badges in README.md to $VERSION"
+          fi
+      
+      - name: Commit documentation updates
+        env:
+          VERSION: ${{ needs.detect-version-change.outputs.new-version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          if git diff --quiet; then
+            echo "No documentation changes to commit"
+          else
+            git add README.md
+            git commit -m "docs: update version badges to v${VERSION}"
+            git push
+            echo "✅ Committed documentation updates"
+          fi
+
+  notify-completion:
+    name: Notify Release Completion
+    runs-on: ubuntu-latest
+    needs: [detect-version-change, create-release, publish-npm, build-docker, update-documentation]
+    if: always() && needs.detect-version-change.outputs.version-changed == 'true'
+    steps:
+      - name: Create release summary
+        run: |
+          VERSION="${{ needs.detect-version-change.outputs.new-version }}"
+          RELEASE_URL="https://github.com/${{ github.repository }}/releases/tag/v$VERSION"
+          
+          echo "## 🎉 Release v$VERSION Published Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Completed Tasks:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # Check job statuses
+          if [ "${{ needs.create-release.result }}" = "success" ]; then
+            echo "- ✅ GitHub Release created: [$RELEASE_URL]($RELEASE_URL)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ GitHub Release creation failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.publish-npm.result }}" = "success" ]; then
+            echo "- ✅ NPM package published: [npmjs.com/package/n8n-mcp](https://www.npmjs.com/package/n8n-mcp)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ NPM publishing failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.build-docker.result }}" = "success" ]; then
+            echo "- ✅ Docker images built and pushed" >> $GITHUB_STEP_SUMMARY
+            echo "  - Standard: \`ghcr.io/czlonkowski/n8n-mcp:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+            echo "  - Railway: \`ghcr.io/czlonkowski/n8n-mcp-railway:v$VERSION\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ❌ Docker image building failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          if [ "${{ needs.update-documentation.result }}" = "success" ]; then
+            echo "- ✅ Documentation updated" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ⚠️ Documentation update skipped or failed" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Installation:" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "# NPM" >> $GITHUB_STEP_SUMMARY
+          echo "npx n8n-mcp" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Docker" >> $GITHUB_STEP_SUMMARY
+          echo "docker run -p 3000:3000 ghcr.io/czlonkowski/n8n-mcp:v$VERSION" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          
+          echo "🎉 Release automation completed for v$VERSION!"

.github/workflows/secret-scan.yml

@@ -0,0 +1,39 @@
+name: Secret Scan
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Minimal permissions: secretlint only needs to read repository contents.
+# The workflow does not comment on PRs, upload artifacts, or modify state.
+permissions:
+  contents: read
+
+jobs:
+  secretlint:
+    name: secretlint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          # Full history lets secretlint see any new files introduced in a PR
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
+        run: npm ci --ignore-scripts --legacy-peer-deps
+
+      - name: Run secretlint
+        # Scan everything except what .secretlintignore excludes. The pre-commit
+        # hook only scans staged files (fast); this CI job is the authoritative
+        # check that catches anything that slipped through --no-verify.
+        run: npx secretlint --maskSecrets "**/*" "**/.*"

.github/workflows/test.yml

@@ -0,0 +1,325 @@
+name: Test Suite
+on:
+  push:
+    branches: [main, feat/comprehensive-testing-suite]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - '**.txt'
+      - 'docs/**'
+      - 'examples/**'
+      - '.github/FUNDING.yml'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/pull_request_template.md'
+      - '.gitignore'
+      - 'LICENSE*'
+      - 'ATTRIBUTION.md'
+      - 'SECURITY.md'
+      - 'CODE_OF_CONDUCT.md'
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  checks: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15  # Increased from 10 to accommodate larger database with community nodes
+    env:
+      # A boolean flag (not the secrets themselves) recording whether a live n8n
+      # instance is configured, so the live-integration step can gate on it without
+      # the N8N_API_* values being exposed to every step in the job. The live tests
+      # need BOTH the URL and the key (getN8nCredentials() throws if either is
+      # missing), and both are empty on Dependabot/fork PRs — so require both here,
+      # otherwise a partially-configured instance would run the step and then fail.
+      HAS_N8N_INSTANCE: ${{ secrets.N8N_API_URL != '' && secrets.N8N_API_KEY != '' }}
+    steps:
+      - uses: actions/checkout@v7
+      
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+      
+      - name: Install dependencies
+        # --legacy-peer-deps: n8n-nodes-base 2.20.x pulls in mappersmith with a `diff`
+        # peer that conflicts with ts-node's `diff@^4`; npm 7+ strict resolution leaves
+        # the lock internally inconsistent. Match local dev (.npmrc legacy-peer-deps=true).
+        run: npm ci --legacy-peer-deps
+      
+      # Verify test environment setup
+      - name: Verify test environment
+        run: |
+          echo "Current directory: $(pwd)"
+          echo "Checking for .env.test file:"
+          ls -la .env.test || echo ".env.test not found!"
+          echo "First few lines of .env.test:"
+          head -5 .env.test || echo "Cannot read .env.test"
+      
+      # Run unit tests first (without MSW)
+      - name: Run unit tests with coverage
+        run: npm run test:unit -- --coverage --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=junit
+        env:
+          CI: true
+      
+      # Pre-build the Docker test image used by tests/integration/docker/*.test.ts
+      # Two test files used to build it independently inside their beforeAll hooks; the
+      # builder stage does an `npm install` from the public registry which intermittently
+      # fails on CI runners and tanked the entire test job. Building it here once gets us:
+      #  - one build attempt instead of two
+      #  - a clear, separately-visible CI step when the npm registry is flaky
+      #  - the test suite degrades to skipped tests if this step fails (won't block PRs)
+      - name: Build Docker test image
+        run: npm run docker:test:build
+        timeout-minutes: 8
+        continue-on-error: true
+
+      # Offline integration suites (database, security, mcp-protocol, workflow-diff,
+      # templates, docker, …). These need no live instance, so they always run and
+      # stay a blocking gate on every PR — Dependabot and forks included. Only the
+      # live n8n-api / ai-validation suites are excluded here (they run in the next
+      # step). MSW setup applies as configured.
+      - name: Run integration tests (offline suites)
+        run: npm run test:integration -- --exclude 'tests/integration/n8n-api/**' --exclude 'tests/integration/ai-validation/**' --reporter=default --reporter=junit
+        env:
+          CI: true
+
+      # Live n8n-API + AI-validation suites hit a real instance via the N8N_API_*
+      # secrets, which are unavailable on Dependabot and fork PRs (there every file
+      # here fails outright, turning the required `test` check permanently red). Skip
+      # them when no instance is configured; on in-repo PRs the secret is present so
+      # they run and remain a blocking gate. Secrets are scoped to this step only.
+      - name: Run integration tests (live n8n instance)
+        if: ${{ env.HAS_N8N_INSTANCE == 'true' }}
+        run: npm run test:integration -- tests/integration/n8n-api tests/integration/ai-validation --reporter=default --reporter=junit
+        env:
+          CI: true
+          N8N_API_URL: ${{ secrets.N8N_API_URL }}
+          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+          N8N_TEST_WEBHOOK_GET_URL: ${{ secrets.N8N_TEST_WEBHOOK_GET_URL }}
+          N8N_TEST_WEBHOOK_POST_URL: ${{ secrets.N8N_TEST_WEBHOOK_POST_URL }}
+          N8N_TEST_WEBHOOK_PUT_URL: ${{ secrets.N8N_TEST_WEBHOOK_PUT_URL }}
+          N8N_TEST_WEBHOOK_DELETE_URL: ${{ secrets.N8N_TEST_WEBHOOK_DELETE_URL }}
+      
+      # Generate test summary
+      - name: Generate test summary
+        if: always()
+        run: node scripts/generate-test-summary.js
+      
+      # Generate detailed reports
+      - name: Generate detailed reports
+        if: always()
+        run: node scripts/generate-detailed-reports.js
+      
+      # Upload test results artifacts
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            test-results/
+            test-summary.md
+            test-reports/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage artifacts
+      - name: Upload coverage reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ github.run_number }}-${{ github.run_attempt }}
+          path: |
+            coverage/
+          retention-days: 30
+          if-no-files-found: warn
+      
+      # Upload coverage to Codecov
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+          verbose: true
+      
+      # Run linting
+      - name: Run linting
+        run: npm run lint
+      
+      # Run type checking
+      - name: Run type checking
+        run: npm run typecheck
+      
+      # Create test report comment for PRs
+      - name: Create test report comment
+        if: github.event_name == 'pull_request' && always()
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            const fs = require('fs');
+            let summary = '## Test Results\n\nTest summary generation failed.';
+            
+            try {
+              if (fs.existsSync('test-summary.md')) {
+                summary = fs.readFileSync('test-summary.md', 'utf8');
+              }
+            } catch (error) {
+              console.error('Error reading test summary:', error);
+            }
+            
+            try {
+              // Find existing comment
+              const { data: comments } = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+              });
+              
+              const botComment = comments.find(comment => 
+                comment.user.type === 'Bot' && 
+                comment.body.includes('## Test Results')
+              );
+              
+              if (botComment) {
+                // Update existing comment
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: summary
+                });
+              } else {
+                // Create new comment
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  body: summary
+                });
+              }
+            } catch (error) {
+              console.error('Failed to create/update PR comment:', error.message);
+              console.log('This is likely due to insufficient permissions for external PRs.');
+              console.log('Test results have been saved to the job summary instead.');
+            }
+      
+      # Generate job summary
+      - name: Generate job summary
+        if: always()
+        run: |
+          echo "# Test Run Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -f test-summary.md ]; then
+            cat test-summary.md >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Test summary generation failed." >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## 📥 Download Artifacts" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- [Test Results](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+          echo "- [Coverage Report](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})" >> $GITHUB_STEP_SUMMARY
+      
+      # Store test metadata
+      - name: Store test metadata
+        if: always()
+        run: |
+          cat > test-metadata.json << EOF
+          {
+            "run_id": "${{ github.run_id }}",
+            "run_number": "${{ github.run_number }}",
+            "run_attempt": "${{ github.run_attempt }}",
+            "sha": "${{ github.sha }}",
+            "ref": "${{ github.ref }}",
+            "event_name": "${{ github.event_name }}",
+            "repository": "${{ github.repository }}",
+            "actor": "${{ github.actor }}",
+            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "node_version": "$(node --version)",
+            "npm_version": "$(npm --version)"
+          }
+          EOF
+      
+      - name: Upload test metadata
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-metadata-${{ github.run_number }}-${{ github.run_attempt }}
+          path: test-metadata.json
+          retention-days: 30
+
+  # Verify the compiled CommonJS artifact loads under Node's CJS loader (regression guard for #864).
+  # Node 20.19+/22.12+ silently tolerate require() of ESM-only deps; scripts/smoke-cjs-runtime.js
+  # forces the strict loader (--no-experimental-require-module) when the running Node supports it,
+  # so a CJS/ESM mismatch in a shipped dependency (e.g. uuid@14) fails here regardless of the
+  # runner's Node version. The unit suite runs under Vitest's ESM pipeline and cannot catch this;
+  # tsc only type-checks.
+  cjs-runtime:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Load compiled CommonJS artifact under strict CJS loader
+        run: npm run test:cjs-runtime
+
+  # Publish test results as checks
+  publish-results:
+    needs: test
+    runs-on: ubuntu-latest
+    if: always()
+    permissions:
+      checks: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download test results
+        uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+
+      - name: Publish test results
+        uses: dorny/test-reporter@v3
+        if: always()
+        continue-on-error: true
+        with:
+          name: Test Results
+          path: 'artifacts/test-results-*/test-results/junit.xml'
+          reporter: java-junit
+          fail-on-error: false
+          fail-on-empty: false