@mseep/ai-tech-app-agent 1.0.0

package/.env

@@ -0,0 +1,24 @@
+# LambdaTest Configuration
+LAMBDATEST_USERNAME="dineshkumarjdivisionsinc"
+LAMBDATEST_ACCESS_KEY="LT_EKyT3FZ9kwxlLruvGS1TaO7RVDhwAU6Yn89KhG6kP3LColW"
+LAMBDATEST_GRID_URL=https://mobile-hub.lambdatest.com/wd/hub
+
+# Ollama/LLM Configuration
+OLLAMA_BASE_URL=http://localhost:11434
+LLM_MODEL=llama3.2:3b
+LLM_TEMPERATURE=0.1
+LLM_MAX_TOKENS=2000
+
+# MCP Configuration
+MCP_SERVER_PORT=3000
+APPIUM_SERVER_URL=https://mobile-hub.lambdatest.com/wd/hub
+
+# Test Configuration
+DEFAULT_TIMEOUT=30000
+SCREENSHOT_ON_FAILURE=true
+RETRY_FAILED_STEPS=true
+MAX_RETRY_ATTEMPTS=2
+
+# Logging
+LOG_LEVEL=info
+LOG_DIR=./logs

package/.env.example

@@ -0,0 +1,24 @@
+# LambdaTest Configuration
+LAMBDATEST_USERNAME=your_username
+LAMBDATEST_ACCESS_KEY=your_access_key
+LAMBDATEST_GRID_URL=https://mobile-hub.lambdatest.com/wd/hub
+
+# Ollama/LLM Configuration
+OLLAMA_BASE_URL=http://localhost:11434
+LLM_MODEL=llama3.2:3b
+LLM_TEMPERATURE=0.1
+LLM_MAX_TOKENS=2000
+
+# MCP Configuration
+MCP_SERVER_PORT=3000
+APPIUM_SERVER_URL=http://localhost:4723
+
+# Test Configuration
+DEFAULT_TIMEOUT=30000
+SCREENSHOT_ON_FAILURE=true
+RETRY_FAILED_STEPS=true
+MAX_RETRY_ATTEMPTS=2
+
+# Logging
+LOG_LEVEL=info
+LOG_DIR=./logs

package/Jenkinsfile

@@ -0,0 +1,210 @@
+pipeline {
+    agent {
+        kubernetes {
+            yaml """
+apiVersion: v1
+kind: Pod
+metadata:
+  labels:
+    jenkins: agent
+spec:
+  containers:
+  - name: node-appium
+    image: node:20-bullseye
+    command:
+    - cat
+    tty: true
+    env:
+    - name: LAMBDATEST_USERNAME
+      valueFrom:
+        secretKeyRef:
+          name: lambdatest-creds
+          key: username
+    - name: LAMBDATEST_ACCESS_KEY
+      valueFrom:
+        secretKeyRef:
+          name: lambdatest-creds
+          key: accessKey
+    - name: OLLAMA_BASE_URL
+      value: "http://ollama-service:11434"
+    volumeMounts:
+    - name: workspace
+      mountPath: /workspace
+  - name: ollama
+    image: ollama/ollama:latest
+    command:
+    - ollama
+    - serve
+    ports:
+    - containerPort: 11434
+    resources:
+      requests:
+        memory: "4Gi"
+        cpu: "2"
+      limits:
+        memory: "8Gi"
+        cpu: "4"
+  volumes:
+  - name: workspace
+    emptyDir: {}
+"""
+        }
+    }
+    
+    environment {
+        REPO_URL = 'https://github.com/your-org/ai-tech-app-agent.git'
+        TEST_SPEC_DIR = 'tests/nlp-specs'
+        REPORT_DIR = 'reports'
+        LOG_DIR = 'logs'
+    }
+    
+    stages {
+        stage('Setup') {
+            steps {
+                container('node-appium') {
+                    script {
+                        echo "Setting up environment..."
+                        
+                        // Install dependencies
+                        sh '''
+                            apt-get update && apt-get install -y \
+                                openjdk-11-jdk \
+                                android-sdk \
+                                curl \
+                                git
+                        '''
+                        
+                        // Clone repository
+                        sh "git clone ${REPO_URL} /workspace/ai-agent || true"
+                        
+                        // Install Node dependencies
+                        dir('/workspace/ai-agent') {
+                            sh 'npm install'
+                            sh 'npm run build'
+                        }
+                    }
+                }
+                
+                container('ollama') {
+                    script {
+                        echo "Pulling Llama model..."
+                        
+                        // Pull the Llama model (this may take a few minutes first time)
+                        sh 'ollama pull llama3.2:3b || echo "Model already exists"'
+                        
+                        // Verify model is available
+                        sh 'ollama list'
+                    }
+                }
+            }
+        }
+        
+        stage('Health Check') {
+            steps {
+                container('node-appium') {
+                    dir('/workspace/ai-agent') {
+                        script {
+                            echo "Performing health checks..."
+                            
+                            // Check LLM availability
+                            sh 'npm run health'
+                        }
+                    }
+                }
+            }
+        }
+        
+        stage('Validate Test Specs') {
+            steps {
+                container('node-appium') {
+                    dir('/workspace/ai-agent') {
+                        script {
+                            echo "Validating test specifications..."
+                            
+                            sh "npm run validate"
+                        }
+                    }
+                }
+            }
+        }
+        
+        stage('Run AI Tests') {
+            steps {
+                container('node-appium') {
+                    dir('/workspace/ai-agent') {
+                        script {
+                            echo "Executing AI-powered tests..."
+                            
+                            // Run tests with NLP specifications
+                            sh """
+                                npm run test || true
+                            """
+                        }
+                    }
+                }
+            }
+        }
+        
+        stage('Generate Reports') {
+            steps {
+                container('node-appium') {
+                    dir('/workspace/ai-agent') {
+                        script {
+                            echo "Generating test reports..."
+                            
+                            // Archive test results
+                            archiveArtifacts artifacts: "${REPORT_DIR}/**/*", allowEmptyArchive: true
+                            
+                            // Archive logs
+                            archiveArtifacts artifacts: "${LOG_DIR}/**/*", allowEmptyArchive: true
+                            
+                            // Parse and publish results
+                            if (fileExists("${REPORT_DIR}/test-report.json")) {
+                                def report = readJSON file: "${REPORT_DIR}/test-report.json"
+                                
+                                echo "Test Summary:"
+                                echo "  Total: ${report.summary.total}"
+                                echo "  Passed: ${report.summary.passed}"
+                                echo "  Failed: ${report.summary.failed}"
+                                echo "  Skipped: ${report.summary.skipped}"
+                                
+                                // Set build status
+                                if (report.summary.failed > 0) {
+                                    currentBuild.result = 'UNSTABLE'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    post {
+        always {
+            container('node-appium') {
+                dir('/workspace/ai-agent') {
+                    script {
+                        echo "Cleaning up..."
+                        
+                        // Clean up any running processes
+                        sh 'pkill -f "appium" || true'
+                        sh 'pkill -f "node" || true'
+                    }
+                }
+            }
+        }
+        
+        success {
+            echo "AI Test Execution completed successfully!"
+        }
+        
+        failure {
+            echo "AI Test Execution failed. Check logs for details."
+        }
+        
+        unstable {
+            echo "AI Test Execution completed with failures."
+        }
+    }
+}

package/MCP-SERVER-GUIDE.md

@@ -0,0 +1,405 @@
+# MCP Server Management Guide
+
+## Understanding the MCP Server
+
+The **MCP (Model Context Protocol) Server** acts as a bridge between the LLM and Appium. In this architecture:
+
+```
+LLM (Llama 3.2:3b) → MCP Server → Appium → Mobile Device
+```
+
+**Important**: The MCP server **starts automatically** when you run tests, so you typically don't need to start it manually.
+
+## Quick Check: Is Everything Running?
+
+### Option 1: Automated Check Script
+
+```bash
+# Make script executable
+chmod +x scripts/check-mcp-server.sh
+
+# Run the checker
+./scripts/check-mcp-server.sh
+```
+
+### Option 2: Node.js Pre-Test Setup
+
+```bash
+# Run comprehensive setup check
+npm run setup
+
+# Or manually
+node scripts/pre-test-setup.js
+```
+
+### Option 3: Manual Checks
+
+Check each service individually:
+
+```bash
+# 1. Check Ollama (LLM)
+curl http://localhost:11434/api/tags
+
+# 2. Check if llama3.2:3b is available
+ollama list | grep llama3.2
+
+# 3. Check Appium (if local)
+curl http://localhost:4723/status
+
+# 4. Check MCP Server (optional)
+lsof -i :3000
+```
+
+## Starting Services
+
+### 1. Start Ollama (REQUIRED)
+
+**Terminal 1 - Keep this running:**
+```bash
+ollama serve
+```
+
+You should see:
+```
+Listening on 127.0.0.1:11434 (version 0.x.x)
+```
+
+**Verify model is available:**
+```bash
+# In another terminal
+ollama list
+
+# Should show:
+# NAME              ID              SIZE      MODIFIED
+# llama3.2:3b       abc123          2.0 GB    2 hours ago
+```
+
+**If model is missing:**
+```bash
+ollama pull llama3.2:3b
+```
+
+### 2. Start Appium (OPTIONAL - Only for Local Testing)
+
+**Terminal 2 - Only if testing locally:**
+```bash
+appium
+```
+
+**If using LambdaTest:** You don't need to start Appium locally - skip this step.
+
+### 3. MCP Server (AUTO-STARTS)
+
+The MCP server **automatically starts** when you run tests via the `MCPClient.initialize()` method.
+
+**To start manually (optional):**
+```bash
+# Make script executable
+chmod +x scripts/start-mcp-server.sh
+
+# Start MCP server
+./scripts/start-mcp-server.sh
+
+# Or with npm
+npm run start-mcp
+```
+
+**To run in background:**
+```bash
+npx mcp-appium > logs/mcp-server.log 2>&1 &
+```
+
+## Complete Startup Sequence
+
+Here's the recommended order to start everything:
+
+### Step-by-Step:
+
+```bash
+# Terminal 1: Start Ollama
+ollama serve
+
+# Terminal 2: Verify model (in a new tab/window)
+ollama list
+# If llama3.2:3b missing, run: ollama pull llama3.2:3b
+
+# Terminal 3: Check all services
+npm run check-services
+
+# Terminal 4: Run comprehensive setup check
+npm run setup
+
+# If all checks pass, run tests
+npm run test
+```
+
+## Automated Pre-Test Check
+
+The framework automatically runs pre-test checks when you use:
+
+```bash
+npm run test        # Runs pretest script automatically
+npm run test:single # Runs pretest script automatically
+```
+
+To skip pre-test checks:
+```bash
+npm run test:no-check
+```
+
+## Troubleshooting
+
+### Issue 1: "LLM is not available"
+
+**Check:**
+```bash
+# Is Ollama running?
+ps aux | grep ollama
+
+# Can you reach the API?
+curl http://localhost:11434/api/tags
+```
+
+**Fix:**
+```bash
+# Start Ollama
+ollama serve
+
+# In another terminal, verify
+ollama list
+```
+
+### Issue 2: "Cannot connect to Appium server"
+
+**If using LambdaTest (recommended):**
+- ✅ This is normal - you don't need local Appium
+- Check `.env` has correct LambdaTest credentials:
+  ```bash
+  LAMBDATEST_GRID_URL=https://mobile-hub.lambdatest.com/wd/hub
+  LAMBDATEST_USERNAME=your_username
+  LAMBDATEST_ACCESS_KEY=your_key
+  ```
+
+**If testing locally:**
+```bash
+# Start Appium
+appium --allow-cors --log-level info
+```
+
+### Issue 3: "MCP Server not found"
+
+**This is usually OK** - MCP starts automatically.
+
+**To verify MCP can start:**
+```bash
+# Check if mcp-appium is available
+npx mcp-appium --version
+
+# If not found, you might need to install it
+# (Note: mcp-appium might be in development)
+```
+
+### Issue 4: Port 3000 already in use
+
+**Check what's using it:**
+```bash
+lsof -i :3000
+```
+
+**Kill the process:**
+```bash
+kill -9 $(lsof -t -i:3000)
+```
+
+**Or change MCP port in `.env`:**
+```bash
+MCP_SERVER_PORT=3001
+```
+
+### Issue 5: Model not found
+
+```bash
+# Check available models
+ollama list
+
+# Pull the required model
+ollama pull llama3.2:3b
+
+# Verify it's downloaded
+ollama list | grep llama3.2
+```
+
+## Health Check Commands
+
+### Quick Health Check
+```bash
+npm run health
+```
+
+### Comprehensive Check
+```bash
+npm run setup
+```
+
+### Service Status Check
+```bash
+npm run check-services
+```
+
+## Process Management
+
+### Check Running Processes
+
+```bash
+# Check Ollama
+pgrep -f ollama
+
+# Check Appium
+pgrep -f appium
+
+# Check MCP
+pgrep -f mcp-appium
+
+# Check all on port 3000
+lsof -i :3000
+```
+
+### Stop All Services
+
+```bash
+# Stop Ollama
+pkill ollama
+
+# Stop Appium
+pkill -f appium
+
+# Stop MCP
+pkill -f mcp-appium
+
+# Or use the process ID
+kill -9 <PID>
+```
+
+### Restart Services
+
+```bash
+# Stop everything
+pkill ollama
+pkill -f appium
+pkill -f mcp-appium
+
+# Wait a moment
+sleep 2
+
+# Start fresh
+ollama serve &
+# MCP will auto-start with tests
+```
+
+## Running Tests with Service Checks
+
+### Recommended Workflow
+
+```bash
+# 1. One-time setup (ensure Ollama is running)
+ollama serve  # Keep this terminal open
+
+# 2. In a new terminal, run setup check
+npm run setup
+
+# 3. If all checks pass, run tests
+npm run test
+```
+
+### CI/CD Environment
+
+In Jenkins/CI, the Jenkinsfile handles service startup automatically:
+
+```groovy
+stage('Setup') {
+  steps {
+    container('ollama') {
+      sh 'ollama pull llama3.2:3b'
+    }
+  }
+}
+
+stage('Health Check') {
+  steps {
+    sh 'npm run health'
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables for MCP
+
+Add to `.env`:
+
+```bash
+# MCP Server Configuration
+MCP_SERVER_TYPE=mcp-appium
+MCP_SERVER_HOST=localhost
+MCP_SERVER_PORT=3000
+MCP_PROTOCOL=http
+MCP_TIMEOUT=30000
+
+# Appium Configuration
+APPIUM_SERVER_URL=http://localhost:4723
+# Or for LambdaTest:
+# APPIUM_SERVER_URL=https://mobile-hub.lambdatest.com/wd/hub
+
+# Enable/disable MCP features
+MCP_CAPTURE_PAGE_SOURCE=true
+MCP_PARSE_XML=true
+MCP_SCREENSHOT_ON_ERROR=true
+```
+
+## Best Practices
+
+### 1. Keep Ollama Running
+- Start once, keep it running all day
+- Uses ~2-4GB RAM when loaded
+- Fast subsequent requests
+
+### 2. Let MCP Auto-Start
+- Don't start MCP manually unless debugging
+- Framework handles initialization
+- Cleaner process management
+
+### 3. Use Health Checks
+- Run `npm run setup` before test sessions
+- Catches issues early
+- Validates environment
+
+### 4. Monitor Resources
+```bash
+# Check memory usage
+top | grep ollama
+
+# Check if model is loaded
+curl http://localhost:11434/api/tags
+```
+
+### 5. Log Everything
+- MCP logs to `logs/mcp-server.log` if started manually
+- Test runner logs to `logs/combined.log`
+- Check logs when debugging
+
+## Summary Checklist
+
+Before running tests, ensure:
+
+- [ ] Ollama is running (`ollama serve`)
+- [ ] Model is available (`ollama list | grep llama3.2`)
+- [ ] Environment variables are set (`.env` file)
+- [ ] Project is built (`npm run build`)
+- [ ] All checks pass (`npm run setup`)
+
+Then run:
+```bash
+npm run test
+```
+
+The MCP server will start automatically! 🚀