From f4ca680532848dc6a82fbc7c4fda45983efccc7e Mon Sep 17 00:00:00 2001
From: "nasir@endelospay.com" <nasir@endelospay.com>
Date: Fri, 22 Aug 2025 00:21:10 +0500
Subject: [PATCH] feat: add PM2 configuration and deployment setup for remote
 server

- Add Makefile with convenient PM2 commands for development and production
- Add ecosystem.config.js with production/staging/dev environment configurations
- Add comprehensive PM2-GUIDE.md documentation for deployment
- Update package.json with PM2-specific npm scripts
- Fix Chrome extension URL handling to omit standard ports (443/80)
- Hide embedding model and semantic engine sections in popup UI
---
 app/chrome-extension/common/env-config.ts     |  39 +++-
 .../entrypoints/popup/App.vue                 |   4 +-
 app/remote-server/Makefile                    | 110 +++++++++
 app/remote-server/PM2-GUIDE.md                | 213 ++++++++++++++++++
 app/remote-server/ecosystem.config.js         |  95 ++++++++
 app/remote-server/package.json                |  10 +-
 6 files changed, 466 insertions(+), 5 deletions(-)
 create mode 100644 app/remote-server/Makefile
 create mode 100644 app/remote-server/PM2-GUIDE.md
 create mode 100644 app/remote-server/ecosystem.config.js

diff --git a/app/chrome-extension/common/env-config.ts b/app/chrome-extension/common/env-config.ts
index 7ba94ea..66b687d 100644
--- a/app/chrome-extension/common/env-config.ts
+++ b/app/chrome-extension/common/env-config.ts
@@ -15,12 +15,47 @@ console.log('Environment Config Loaded:', {
   REMOTE_SERVER_PORT,
 });
 
+// Helper function to determine if we should include port in URL
+const shouldIncludePort = (host: string, port: string): boolean => {
+  // For localhost/127.0.0.1, always include port
+  if (host === '127.0.0.1' || host === 'localhost') {
+    return true;
+  }
+
+  // For HTTPS domains using standard port 443, don't include port
+  if (port === '443') {
+    return false;
+  }
+
+  // For HTTP domains using standard port 80, don't include port
+  if (port === '80') {
+    return false;
+  }
+
+  // For all other cases, include the port
+  return true;
+};
+
+// Helper function to determine protocol
+const getProtocol = (port: string): { ws: string; http: string } => {
+  if (port === '443') {
+    return { ws: 'wss', http: 'https' };
+  }
+  return { ws: 'ws', http: 'http' };
+};
+
+// Build URLs based on whether port should be included
+const includePort = shouldIncludePort(REMOTE_SERVER_HOST, REMOTE_SERVER_PORT);
+const protocols = getProtocol(REMOTE_SERVER_PORT);
+
+const baseUrl = includePort ? `${REMOTE_SERVER_HOST}:${REMOTE_SERVER_PORT}` : REMOTE_SERVER_HOST;
+
 // Remote Server Configuration
 export const REMOTE_SERVER_CONFIG = {
   HOST: REMOTE_SERVER_HOST,
   PORT: REMOTE_SERVER_PORT,
-  WS_URL: `ws://${REMOTE_SERVER_HOST}:${REMOTE_SERVER_PORT}/chrome`,
-  HTTP_URL: `http://${REMOTE_SERVER_HOST}:${REMOTE_SERVER_PORT}/mcp`,
+  WS_URL: `${protocols.ws}://${baseUrl}/chrome`,
+  HTTP_URL: `${protocols.http}://${baseUrl}/mcp`,
 } as const;
 
 // Default connection settings
diff --git a/app/chrome-extension/entrypoints/popup/App.vue b/app/chrome-extension/entrypoints/popup/App.vue
index a6b15b0..30275dd 100644
--- a/app/chrome-extension/entrypoints/popup/App.vue
+++ b/app/chrome-extension/entrypoints/popup/App.vue
@@ -384,7 +384,7 @@
         </div>
       </div>
 
-      <div class="section">
+      <div class="section" style="display: none">
         <h2 class="section-title">{{ getMessage('semanticEngineLabel') }}</h2>
         <div class="semantic-engine-card">
           <div class="semantic-engine-status">
@@ -416,7 +416,7 @@
         </div>
       </div>
 
-      <div class="section">
+      <div class="section" style="display: none">
         <h2 class="section-title">{{ getMessage('embeddingModelLabel') }}</h2>
 
         <ProgressIndicator
diff --git a/app/remote-server/Makefile b/app/remote-server/Makefile
new file mode 100644
index 0000000..5f0a329
--- /dev/null
+++ b/app/remote-server/Makefile
@@ -0,0 +1,110 @@
+# MCP Remote Server Makefile
+# Provides convenient commands for development and production deployment
+
+.PHONY: help install build start stop restart status logs dev clean test lint format pm2-setup pm2-start pm2-stop pm2-restart pm2-status pm2-logs pm2-delete
+
+# Default target
+help:
+	@echo "MCP Remote Server - Available Commands:"
+	@echo ""
+	@echo "Development:"
+	@echo "  make install     - Install dependencies"
+	@echo "  make build       - Build TypeScript to JavaScript"
+	@echo "  make dev         - Start development server with hot reload"
+	@echo "  make test        - Run tests"
+	@echo "  make lint        - Run ESLint"
+	@echo "  make format      - Format code with Prettier"
+	@echo "  make clean       - Clean build artifacts"
+	@echo ""
+	@echo "Production (Direct):"
+	@echo "  make start       - Build and start server"
+	@echo "  make stop        - Stop server (if running in background)"
+	@echo ""
+	@echo "Production (PM2):"
+	@echo "  make pm2-setup   - Install PM2 globally (requires sudo/admin)"
+	@echo "  make pm2-start   - Start server with PM2"
+	@echo "  make pm2-stop    - Stop PM2 server"
+	@echo "  make pm2-restart - Restart PM2 server"
+	@echo "  make pm2-status  - Show PM2 status"
+	@echo "  make pm2-logs    - Show PM2 logs"
+	@echo "  make pm2-delete  - Delete PM2 process"
+	@echo ""
+
+# Development commands
+install:
+	@echo "Installing dependencies..."
+	npm install
+
+build:
+	@echo "Building TypeScript..."
+	npm run build
+
+dev:
+	@echo "Starting development server..."
+	npm run dev
+
+test:
+	@echo "Running tests..."
+	npm test
+
+lint:
+	@echo "Running ESLint..."
+	npm run lint
+
+format:
+	@echo "Formatting code..."
+	npm run format
+
+clean:
+	@echo "Cleaning build artifacts..."
+	rm -rf dist/
+	rm -rf node_modules/.cache/
+
+# Direct production commands
+start: build
+	@echo "Starting server..."
+	npm start
+
+stop:
+	@echo "Stopping server..."
+	@pkill -f "node dist/index.js" || echo "No server process found"
+
+# PM2 commands
+pm2-setup:
+	@echo "Installing PM2 globally..."
+	npm install -g pm2
+
+pm2-start: build
+	@echo "Starting server with PM2..."
+	pm2 start ecosystem.config.js
+
+pm2-stop:
+	@echo "Stopping PM2 server..."
+	pm2 stop mcp-remote-server
+
+pm2-restart:
+	@echo "Restarting PM2 server..."
+	pm2 restart mcp-remote-server
+
+pm2-status:
+	@echo "PM2 status:"
+	pm2 status
+
+pm2-logs:
+	@echo "Showing PM2 logs..."
+	pm2 logs mcp-remote-server
+
+pm2-delete:
+	@echo "Deleting PM2 process..."
+	pm2 delete mcp-remote-server
+
+# Utility commands
+restart: stop start
+
+status:
+	@echo "Checking server status..."
+	@curl -s http://localhost:3040/health || echo "Server not responding"
+
+logs:
+	@echo "Server logs (if running with PM2):"
+	@pm2 logs mcp-remote-server --lines 50 || echo "Use 'make pm2-logs' for PM2 logs"
diff --git a/app/remote-server/PM2-GUIDE.md b/app/remote-server/PM2-GUIDE.md
new file mode 100644
index 0000000..5f705b6
--- /dev/null
+++ b/app/remote-server/PM2-GUIDE.md
@@ -0,0 +1,213 @@
+# PM2 Deployment Guide for MCP Remote Server
+
+This guide explains how to run the MCP Remote Server using PM2 for production deployment.
+
+## Prerequisites
+
+1. **Node.js** (v18 or higher)
+2. **PM2** (Process Manager)
+
+## Quick Start
+
+### 1. Install PM2 (if not already installed)
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Or using the Makefile
+make pm2-setup
+```
+
+### 2. Start the Server
+
+```bash
+# Using Makefile (recommended)
+make pm2-start
+
+# Or using npm scripts
+npm run pm2:start
+
+# Or directly with PM2
+pm2 start ecosystem.config.js
+```
+
+### 3. Monitor the Server
+
+```bash
+# Check status
+make pm2-status
+# or
+pm2 status
+
+# View logs
+make pm2-logs
+# or
+pm2 logs mcp-remote-server
+
+# Monitor in real-time
+pm2 monit
+```
+
+## Available Commands
+
+### Makefile Commands
+
+```bash
+make pm2-start     # Start server with PM2
+make pm2-stop      # Stop server
+make pm2-restart   # Restart server
+make pm2-status    # Show status
+make pm2-logs      # Show logs
+make pm2-delete    # Delete PM2 process
+```
+
+### NPM Scripts
+
+```bash
+npm run pm2:start    # Start with PM2
+npm run pm2:stop     # Stop server
+npm run pm2:restart  # Restart server
+npm run pm2:reload   # Reload (zero-downtime)
+npm run pm2:status   # Show status
+npm run pm2:logs     # Show logs
+npm run pm2:monit    # Open monitoring dashboard
+```
+
+## Environment Configuration
+
+The server supports multiple environments configured in `ecosystem.config.js`:
+
+### Production
+
+```bash
+pm2 start ecosystem.config.js --env production
+```
+
+- PORT: 3040
+- HOST: 0.0.0.0
+- DOMAIN: https://mcp-browser.qubecare.ai
+
+### Development
+
+```bash
+pm2 start ecosystem.config.js --env development
+```
+
+- PORT: 3040
+- HOST: 0.0.0.0
+- DOMAIN: http://localhost:3040
+
+### Staging
+
+```bash
+pm2 start ecosystem.config.js --env staging
+```
+
+- PORT: 3040
+- HOST: 0.0.0.0
+- DOMAIN: https://staging-mcp-browser.qubecare.ai
+
+## Logs
+
+Logs are stored in the `logs/` directory:
+
+- `logs/combined.log` - All logs
+- `logs/out.log` - Standard output
+- `logs/error.log` - Error logs
+
+## Auto-restart on System Boot
+
+To automatically start the server on system boot:
+
+```bash
+# Save current PM2 processes
+pm2 save
+
+# Generate startup script
+pm2 startup
+
+# Follow the instructions provided by PM2
+```
+
+## Monitoring and Management
+
+### Real-time Monitoring
+
+```bash
+pm2 monit
+```
+
+### Process Information
+
+```bash
+pm2 show mcp-remote-server
+```
+
+### Resource Usage
+
+```bash
+pm2 list
+```
+
+## Troubleshooting
+
+### Server Won't Start
+
+1. Check if port 3040 is available
+2. Verify the build was successful: `npm run build`
+3. Check logs: `pm2 logs mcp-remote-server`
+
+### High Memory Usage
+
+The server is configured to restart if memory usage exceeds 1GB. You can adjust this in `ecosystem.config.js`:
+
+```javascript
+max_memory_restart: '1G'; // Change to desired limit
+```
+
+### Connection Issues
+
+1. Verify the server is running: `make pm2-status`
+2. Check health endpoint: `curl http://localhost:3040/health`
+3. Review error logs: `pm2 logs mcp-remote-server --err`
+
+## Production Deployment
+
+For production deployment, ensure:
+
+1. **Environment Variables**: Update `.env` file or ecosystem config
+2. **Domain Configuration**: Set correct DOMAIN in ecosystem.config.js
+3. **SSL/TLS**: Configure reverse proxy (nginx/apache) for HTTPS
+4. **Firewall**: Open port 3040 or configure reverse proxy
+5. **Monitoring**: Set up external monitoring for the health endpoint
+
+## Security Considerations
+
+1. **Firewall**: Restrict access to port 3040
+2. **Reverse Proxy**: Use nginx/apache for SSL termination
+3. **Environment Variables**: Keep sensitive data in environment variables
+4. **Updates**: Regularly update dependencies
+
+## Example Production Setup
+
+```bash
+# 1. Clone and setup
+git clone <repository>
+cd app/remote-server
+npm install
+
+# 2. Configure environment
+cp .env.example .env
+# Edit .env with production values
+
+# 3. Start with PM2
+make pm2-start
+
+# 4. Setup auto-restart
+pm2 save
+pm2 startup
+
+# 5. Monitor
+make pm2-status
+```
diff --git a/app/remote-server/ecosystem.config.js b/app/remote-server/ecosystem.config.js
new file mode 100644
index 0000000..97b6688
--- /dev/null
+++ b/app/remote-server/ecosystem.config.js
@@ -0,0 +1,95 @@
+module.exports = {
+  apps: [
+    {
+      name: 'mcp-remote-server',
+      script: 'dist/index.js',
+      cwd: __dirname,
+      instances: 1,
+      autorestart: true,
+      watch: false,
+      max_memory_restart: '1G',
+      env: {
+        NODE_ENV: 'production',
+        PORT: 3040,
+        HOST: '0.0.0.0',
+        DOMAIN: 'https://mcp-browser.qubecare.ai',
+      },
+      env_development: {
+        NODE_ENV: 'development',
+        PORT: 3040,
+        HOST: '0.0.0.0',
+        DOMAIN: 'http://localhost:3040',
+      },
+      env_staging: {
+        NODE_ENV: 'staging',
+        PORT: 3040,
+        HOST: '0.0.0.0',
+        DOMAIN: 'https://staging-mcp-browser.qubecare.ai',
+      },
+      // Logging configuration
+      log_file: './logs/combined.log',
+      out_file: './logs/out.log',
+      error_file: './logs/error.log',
+      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
+
+      // Process management
+      min_uptime: '10s',
+      max_restarts: 10,
+      restart_delay: 4000,
+
+      // Advanced PM2 features
+      exec_mode: 'fork',
+      kill_timeout: 5000,
+      listen_timeout: 3000,
+
+      // Health monitoring
+      health_check_grace_period: 3000,
+
+      // Environment-specific overrides
+      merge_logs: true,
+
+      // Custom startup script (optional)
+      pre_start: 'npm run build',
+
+      // Post-deployment hooks (optional)
+      post_start: 'echo "MCP Remote Server started successfully"',
+
+      // Graceful shutdown
+      shutdown_with_message: true,
+
+      // Source map support for better error traces
+      source_map_support: true,
+
+      // Node.js specific options
+      node_args: '--max-old-space-size=1024',
+
+      // Custom environment variables from .env file
+      env_file: '.env',
+    },
+  ],
+
+  // Deployment configuration (optional)
+  deploy: {
+    production: {
+      user: 'deploy',
+      host: 'your-server.com',
+      ref: 'origin/main',
+      repo: 'git@github.com:your-username/your-repo.git',
+      path: '/var/www/mcp-remote-server',
+      'pre-deploy-local': '',
+      'post-deploy':
+        'npm install && npm run build && pm2 reload ecosystem.config.js --env production',
+      'pre-setup': '',
+    },
+    staging: {
+      user: 'deploy',
+      host: 'staging-server.com',
+      ref: 'origin/develop',
+      repo: 'git@github.com:your-username/your-repo.git',
+      path: '/var/www/mcp-remote-server-staging',
+      'pre-deploy-local': '',
+      'post-deploy': 'npm install && npm run build && pm2 reload ecosystem.config.js --env staging',
+      'pre-setup': '',
+    },
+  },
+};
diff --git a/app/remote-server/package.json b/app/remote-server/package.json
index 34dfe5f..a11a648 100644
--- a/app/remote-server/package.json
+++ b/app/remote-server/package.json
@@ -13,7 +13,15 @@
     "test": "jest",
     "lint": "eslint 'src/**/*.{js,ts}'",
     "lint:fix": "eslint 'src/**/*.{js,ts}' --fix",
-    "format": "prettier --write 'src/**/*.{js,ts,json}'"
+    "format": "prettier --write 'src/**/*.{js,ts,json}'",
+    "pm2:start": "npm run build && pm2 start ecosystem.config.js",
+    "pm2:stop": "pm2 stop mcp-remote-server",
+    "pm2:restart": "pm2 restart mcp-remote-server",
+    "pm2:reload": "pm2 reload mcp-remote-server",
+    "pm2:delete": "pm2 delete mcp-remote-server",
+    "pm2:status": "pm2 status",
+    "pm2:logs": "pm2 logs mcp-remote-server",
+    "pm2:monit": "pm2 monit"
   },
   "keywords": [
     "mcp",