@rishibhushan/jenkins-mcp-server 1.0.6 → 1.1.0

package/README.md

@@ -4,8 +4,31 @@
 
 Designed to work seamlessly with automation clients such as:
 - 🖥️ **VS Code MCP** - Direct integration with Claude in VS Code
+- 🖥️ **Claude Desktop** - AI-powered Jenkins automation
 - 🔌 **Any MCP-compatible client** - Universal compatibility
 
+## ✨ What's New in v1.1.0
+
+### 🚀 Performance Enhancements
+- ⚡ **10x faster** - Client connection caching for repeated operations
+- 📊 **Smart caching** - Job list caching with 30-60s TTL (5-10x improvement)
+- 🎯 **Optimized queries** - Reduced API calls by 33-83%
+
+### 🛡️ Reliability Improvements
+- ✅ **86% validation coverage** - Input validation on 18/21 tools
+- ⏱️ **Configurable timeouts** - No more hanging API calls
+- 💬 **Better error messages** - Clear troubleshooting steps
+- 🏥 **Health check tool** - Instant diagnostics
+
+### 🎛️ Advanced Features
+- 📦 **Batch operations** - Trigger up to 20 builds at once
+- 📈 **Metrics & telemetry** - Track tool usage and performance
+- 🗂️ **Cache management** - Monitor and control caching
+- 📊 **Console improvements** - Line-based truncation with tail mode
+- 🎨 **Structured logging** - Better debugging with JSON logs
+
+---
+
 ## ✨ About codebase
 
 - ✅ **Codebase** - cleaner, more maintainable
@@ -14,6 +37,8 @@ Designed to work seamlessly with automation clients such as:
 - ✅ **Cross-platform** - Seamless support for Windows, macOS, and Linux
 - ✅ **Logging** - Professional logging with `--verbose` flag
 - ✅ **Dependency management** - Automatic detection and installation
+- ✅ **Performance** - 10x faster with intelligent caching and optimization
+- ✅ **Reliability** - Comprehensive input validation and error handling
 
 ---
 
@@ -25,25 +50,26 @@ This project includes:
 - 🔄 Automatic virtual environment creation + dependency installation
 - 🌐 Corporate proxy/certificate auto-detection support
 - 🪟 Windows, macOS, and Linux support
-- 🛠️ **20 Jenkins management tools**
+- 🛠️ **26 Jenkins management tools** (upgraded from 20!)
 
 ### 🧩 Build Operations
 | Tool Name | Description | Required Fields | Optional Fields |
 |---|---|---|---|
 | `trigger-build` | Trigger a Jenkins job build with optional parameters | `job_name` | `parameters` |
 | `stop-build` | Stop a running Jenkins build | `job_name`, `build_number` | *(none)* |
+| `trigger-multiple-builds` | **NEW!** Trigger builds for multiple jobs at once | `job_names` | `parameters`, `wait_for_start` |
 
 ### 📊 Job Information
 | Tool Name | Description | Required Fields | Optional Fields |
 |---|---|---|---|
-| `list-jobs` | List all Jenkins jobs with optional filtering | *(none)* | `filter` |
-| `get-job-details` | Get detailed information about a Jenkins job | `job_name` | *(none)* |
+| `list-jobs` | List all Jenkins jobs with optional filtering **and caching** | *(none)* | `filter`, `use_cache` |
+| `get-job-details` | Get detailed information about a Jenkins job | `job_name` | `max_recent_builds` |
 
 ### 🛠️ Build Information
 | Tool Name | Description | Required Fields | Optional Fields |
 |---|---|---|---|
 | `get-build-info` | Get information about a specific build | `job_name`, `build_number` | *(none)* |
-| `get-build-console` | Get console output from a build | `job_name`, `build_number` | *(none)* |
+| `get-build-console` | Get console output with **smart truncation** | `job_name`, `build_number` | `max_lines`, `tail_only` |
 | `get-last-build-number` | Get the last build number for a job | `job_name` | *(none)* |
 | `get-last-build-timestamp` | Get the timestamp of the last build | `job_name` | *(none)* |
 
@@ -70,6 +96,17 @@ This project includes:
 | `get-queue-info` | Get Jenkins build queue info | *(none)* | *(none)* |
 | `list-nodes` | List all Jenkins nodes | *(none)* | *(none)* |
 | `get-node-info` | Get information about a Jenkins node | `node_name` | *(none)* |
+| `health-check` | **NEW!** Run diagnostics on Jenkins connection | *(none)* | *(none)* |
+
+### 📊 Monitoring & Management
+| Tool Name | Description | Required Fields | Optional Fields |
+|---|---|---|---|
+| `get-cache-stats` | **NEW!** Get cache statistics and information | *(none)* | *(none)* |
+| `clear-cache` | **NEW!** Clear all cached data | *(none)* | *(none)* |
+| `get-metrics` | **NEW!** Get usage metrics and performance stats | *(none)* | `tool_name` |
+| `configure-webhook` | **NEW!** Configure webhook notifications | `job_name`, `webhook_url`, `events` | *(none)* |
+
+For detailed technical documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ---
 
@@ -161,12 +198,7 @@ Add to your VS Code `settings.json`:
 
 ### Option 2: Environment File (.env)
 
-Rename `.env.template` to `.env`
-```bash
-cp .env.template .env
-```
-
-In the `.env` file in your project directory:
+Create a file `.env` in your local:
 
 ```bash
 JENKINS_URL=http://jenkins.example.com:8080
@@ -214,7 +246,11 @@ Settings are loaded in this order (later overrides earlier):
 
 ### Option 1: Using npx (No Installation Required)
 ```bash
+# if .env file is located in the current directory
 npx @rishibhushan/jenkins-mcp-server --env-file .env
+
+# OR if .env file is located in /path/to/.env
+npx @rishibhushan/jenkins-mcp-server --env-file /path/to/.env
 ```
 
 ### Option 2: Global Installation
@@ -231,10 +267,6 @@ jenkins-mcp-server --env-file .env
 npx github:rishibhushan/jenkins_mcp_server --env-file .env
 ```
 
-[//]: # ([![npm version](https://badge.fury.io/js/jenkins-mcp-server.svg)](https://www.npmjs.com/package/@rishibhushan/jenkins-mcp-server))
-
-[//]: # ([![npm downloads](https://img.shields.io/npm/dm/jenkins-mcp-server.svg)](https://www.npmjs.com/package/@rishibhushan/jenkins-mcp-server))
-
 ---
 
 This automatically:
@@ -471,13 +503,15 @@ if result['build_number']:
 
 ## 🔧 Troubleshooting
 
-### Python Not Found
+### Common Issues
+
+#### Python Not Found
 ```
 Error: Python 3 is required but not found.
 ```
 **Solution**: Install Python 3.8+ from https://www.python.org/downloads/
 
-### Configuration Issues
+#### Configuration Issues
 ```
 ERROR: Jenkins configuration is incomplete!
 ```
@@ -495,7 +529,7 @@ env | grep JENKINS
 cat ~/.config/Code/User/settings.json | grep jenkins
 ```
 
-### Connection Failed
+#### Connection Failed
 ```
 Failed to connect to Jenkins at http://localhost:8080
 ```
@@ -505,7 +539,7 @@ Failed to connect to Jenkins at http://localhost:8080
 3. Verify URL is correct (include port if needed)
 4. Test authentication credentials
 
-### Dependency Installation Failed
+#### Dependency Installation Failed
 ```
 Failed to install dependencies
 ```
@@ -514,6 +548,538 @@ Failed to install dependencies
 2. If behind a proxy, set `HTTP_PROXY` and `HTTPS_PROXY` environment variables
 3. Try manual installation: `.venv/bin/pip install -r requirements.txt`
 
+---
+
+### 🚨 VPN & Corporate Network Issues
+
+If you're experiencing timeout issues with Claude Desktop or other MCP clients when using a VPN or corporate network, this section provides step-by-step solutions.
+
+#### Symptom: Request Timeout After 60 Seconds
+
+**Error in logs:**
+```
+McpError: MCP error -32001: Request timed out
+Server transport closed unexpectedly
+```
+
+**Root Cause**: The Python process spawned by `npx` may not properly inherit VPN network routing, causing it to fail when connecting to internal Jenkins servers.
+
+---
+
+### Solution 1: Bypass Proxy for PyPI (For Dependency Installation Issues)
+
+If you're getting proxy errors during dependency installation:
+
+**Add to your `claude_desktop_config.json`:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "npx",
+      "args": [
+        "@rishibhushan/jenkins-mcp-server",
+        "--env-file",
+        "/path/to/.env"
+      ],
+      "env": {
+        "NO_PROXY": "pypi.org,pypi.python.org,files.pythonhosted.org",
+        "PIP_NO_PROXY": "pypi.org,pypi.python.org,files.pythonhosted.org"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Solution 2: Use Direct Python Execution (Recommended for VPN)
+
+This bypasses the `npx` wrapper entirely and uses Python directly, which properly inherits your system's network routing.
+
+#### Step 1: Locate the Installed Package
+
+**For macOS/Linux:**
+```bash
+# Find the npx cache directory
+PACKAGE_DIR=$(find ~/.npm/_npx -name "jenkins-mcp-server" -type d 2>/dev/null | head -1)
+echo $PACKAGE_DIR
+```
+
+**For Windows (PowerShell):**
+```powershell
+# Find the npx cache directory
+$PACKAGE_DIR = Get-ChildItem -Path "$env:LOCALAPPDATA\npm-cache\_npx" -Recurse -Directory -Filter "jenkins-mcp-server" | Select-Object -First 1 -ExpandProperty FullName
+Write-Host $PACKAGE_DIR
+```
+
+The output will be something like:
+- **macOS/Linux**: `/Users/username/.npm/_npx/<hash>/node_modules/@rishibhushan/jenkins-mcp-server`
+- **Windows**: `C:\Users\username\AppData\Local\npm-cache\_npx\<hash>\node_modules\@rishibhushan\jenkins-mcp-server`
+
+#### Step 2: Update Claude Desktop Configuration
+
+Replace `<PACKAGE_DIR>` with the path from Step 1:
+
+**macOS/Linux:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "<PACKAGE_DIR>/.venv/bin/python",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "/path/to/your/.env"
+      ],
+      "env": {
+        "PYTHONPATH": "<PACKAGE_DIR>/src"
+      }
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "<PACKAGE_DIR>\\.venv\\Scripts\\python.exe",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "C:\\path\\to\\your\\.env"
+      ],
+      "env": {
+        "PYTHONPATH": "<PACKAGE_DIR>\\src"
+      }
+    }
+  }
+}
+```
+
+#### Step 3: Example Configuration
+
+**Complete example for macOS:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "/Users/username/.npm/_npx/a88b5f55f40c4229/node_modules/@rishibhushan/jenkins-mcp-server/.venv/bin/python",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "/Users/username/projects/jenkins_mcp_server/.env"
+      ],
+      "env": {
+        "PYTHONPATH": "/Users/username/.npm/_npx/a88b5f55f40c4229/node_modules/@rishibhushan/jenkins-mcp-server/src"
+      }
+    }
+  }
+}
+```
+
+#### Step 4: Restart Claude Desktop
+
+1. **Connect to your VPN first**
+2. Quit Claude Desktop completely
+3. Start Claude Desktop
+4. Check the MCP server connection in settings
+
+---
+
+### Solution 3: Use Local Git Clone (Best for Development)
+
+If you're developing or frequently updating, use a local clone:
+
+#### Step 1: Clone and Setup
+```bash
+# Clone the repository
+git clone https://github.com/rishibhushan/jenkins_mcp_server.git
+cd jenkins_mcp_server
+
+# Create virtual environment and install dependencies
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+#### Step 2: Configure Claude Desktop
+
+**macOS/Linux:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "/path/to/jenkins_mcp_server/.venv/bin/python",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "/path/to/jenkins_mcp_server/.env"
+      ],
+      "env": {
+        "PYTHONPATH": "/path/to/jenkins_mcp_server/src"
+      }
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "C:\\path\\to\\jenkins_mcp_server\\.venv\\Scripts\\python.exe",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "C:\\path\\to\\jenkins_mcp_server\\.env"
+      ],
+      "env": {
+        "PYTHONPATH": "C:\\path\\to\\jenkins_mcp_server\\src"
+      }
+    }
+  }
+}
+```
+---
+
+### Solution 4: Use Global Installation with Direct Python Path
+
+If you prefer to use global installation but still face VPN/timeout issues, you can combine both approaches.
+
+#### Step 1: Install Globally
+
+**Disconnect from VPN first** (to avoid proxy issues during installation):
+```bash
+# Install globally
+npm install -g @rishibhushan/jenkins-mcp-server
+
+# Verify installation
+jenkins-mcp-server --version
+```
+
+#### Step 2: Locate Global Installation Directory
+
+**For macOS/Linux:**
+```bash
+# Find the global npm directory
+npm root -g
+
+# This typically returns something like:
+# /usr/local/lib/node_modules
+# or
+# /Users/username/.npm-global/lib/node_modules
+
+# Your package will be at:
+# <npm-root>/@rishibhushan/jenkins-mcp-server
+```
+
+**For Windows (PowerShell):**
+```powershell
+# Find the global npm directory
+npm root -g
+
+# This typically returns something like:
+# C:\Users\username\AppData\Roaming\npm\node_modules
+
+# Your package will be at:
+# <npm-root>\@rishibhushan\jenkins-mcp-server
+```
+
+#### Step 3: Find the Python Path
+
+Once you know the installation directory:
+
+**macOS/Linux:**
+```bash
+# If npm root -g shows: /usr/local/lib/node_modules
+# Your Python path will be:
+/usr/local/lib/node_modules/@rishibhushan/jenkins-mcp-server/.venv/bin/python
+
+# Verify it exists:
+ls -la /usr/local/lib/node_modules/@rishibhushan/jenkins-mcp-server/.venv/bin/python
+```
+
+**Windows:**
+```powershell
+# If npm root -g shows: C:\Users\username\AppData\Roaming\npm\node_modules
+# Your Python path will be:
+C:\Users\username\AppData\Roaming\npm\node_modules\@rishibhushan\jenkins-mcp-server\.venv\Scripts\python.exe
+
+# Verify it exists:
+Test-Path "C:\Users\username\AppData\Roaming\npm\node_modules\@rishibhushan\jenkins-mcp-server\.venv\Scripts\python.exe"
+```
+
+#### Step 4: Configure Your MCP Client
+
+**For Claude Desktop (macOS/Linux):**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "/usr/local/lib/node_modules/@rishibhushan/jenkins-mcp-server/.venv/bin/python",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "/path/to/your/.env"
+      ],
+      "env": {
+        "PYTHONPATH": "/usr/local/lib/node_modules/@rishibhushan/jenkins-mcp-server/src"
+      }
+    }
+  }
+}
+```
+
+**For Claude Desktop (Windows):**
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\@rishibhushan\\jenkins-mcp-server\\.venv\\Scripts\\python.exe",
+      "args": [
+        "-m",
+        "jenkins_mcp_server",
+        "--env-file",
+        "C:\\path\\to\\your\\.env"
+      ],
+      "env": {
+        "PYTHONPATH": "C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\@rishibhushan\\jenkins-mcp-server\\src"
+      }
+    }
+  }
+}
+```
+
+**For Other MCP Clients:**
+
+Use the same pattern - replace the `command` with the direct Python path and set the `PYTHONPATH` environment variable.
+
+#### Step 5: Test and Use
+
+1. **Connect to your VPN**
+2. **Restart your MCP client** (Claude Desktop, VS Code, etc.)
+3. **Verify the connection** works
+
+#### Why This Solution Works
+
+- ✅ **Persistent installation** - No need to download on each use
+- ✅ **Proper network routing** - Python process inherits VPN routing
+- ✅ **Works across sessions** - Survives VPN connect/disconnect cycles
+- ✅ **Easy updates** - Just run `npm update -g @rishibhushan/jenkins-mcp-server`
+- ✅ **Universal** - Works with any MCP client (Claude, VS Code, etc.)
+
+#### Quick Reference Commands
+```bash
+# Find your global installation
+npm root -g
+
+# Update global installation
+npm update -g @rishibhushan/jenkins-mcp-server
+
+# Uninstall if needed
+npm uninstall -g @rishibhushan/jenkins-mcp-server
+
+# Test the Python path works
+/path/to/global/installation/.venv/bin/python -m jenkins_mcp_server --help
+```
+
+---
+
+### 🧪 Testing Your Connection
+
+Before configuring MCP clients, test your Jenkins connection manually:
+
+#### Create a Test Script
+
+Save this as `test_jenkins_connection.py`:
+
+```python
+#!/usr/bin/env python3
+"""
+Test Jenkins connectivity for MCP server troubleshooting
+"""
+import os
+import sys
+import time
+import requests
+from dotenv import load_dotenv
+
+def test_connection():
+    # Load environment
+    env_file = '/path/to/your/.env'  # Update this path
+    print(f"Loading environment from: {env_file}")
+    load_dotenv(env_file)
+    
+    url = os.getenv('JENKINS_URL')
+    username = os.getenv('JENKINS_USERNAME')
+    token = os.getenv('JENKINS_TOKEN')
+    
+    print(f"\nJenkins Configuration:")
+    print(f"  URL: {url}")
+    print(f"  Username: {username}")
+    print(f"  Token: {'***' if token else 'NOT SET'}")
+    
+    # Test 1: DNS Resolution
+    print(f"\n[Test 1] Testing DNS resolution...")
+    import socket
+    try:
+        hostname = url.split('://')[1].split(':')[0]
+        ip = socket.gethostbyname(hostname)
+        print(f"  ✓ DNS resolved: {hostname} -> {ip}")
+    except Exception as e:
+        print(f"  ✗ DNS resolution failed: {e}")
+        return False
+    
+    # Test 2: Basic connectivity
+    print(f"\n[Test 2] Testing basic HTTP connectivity...")
+    try:
+        start = time.time()
+        response = requests.get(f"{url}/api/json", timeout=5)
+        elapsed = time.time() - start
+        print(f"  ✓ Connection successful (no auth): {response.status_code} in {elapsed:.2f}s")
+    except requests.exceptions.Timeout:
+        print(f"  ✗ Connection timed out after 5 seconds")
+        return False
+    except Exception as e:
+        print(f"  ✗ Connection failed: {e}")
+        return False
+    
+    # Test 3: Authenticated request
+    print(f"\n[Test 3] Testing authenticated request...")
+    try:
+        start = time.time()
+        response = requests.get(
+            f"{url}/api/json",
+            auth=(username, token),
+            timeout=10
+        )
+        elapsed = time.time() - start
+        print(f"  ✓ Authenticated request: {response.status_code} in {elapsed:.2f}s")
+        
+        if response.status_code == 200:
+            data = response.json()
+            print(f"  ✓ Jenkins version: {data.get('version', 'unknown')}")
+            print(f"  ✓ Number of jobs: {len(data.get('jobs', []))}")
+        elif response.status_code == 401:
+            print(f"  ✗ Authentication failed - check username/token")
+            return False
+        elif response.status_code == 403:
+            print(f"  ✗ Access forbidden - check permissions")
+            return False
+    except Exception as e:
+        print(f"  ✗ Authenticated request failed: {e}")
+        return False
+    
+    # Test 4: python-jenkins library
+    print(f"\n[Test 4] Testing python-jenkins library...")
+    try:
+        import jenkins
+        start = time.time()
+        server = jenkins.Jenkins(url, username=username, password=token)
+        user = server.get_whoami()
+        elapsed = time.time() - start
+        print(f"  ✓ python-jenkins connection: {user['fullName']} in {elapsed:.2f}s")
+    except Exception as e:
+        print(f"  ✗ python-jenkins failed: {e}")
+        return False
+    
+    print(f"\n✓ All tests passed! Jenkins MCP Server should work.")
+    return True
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Jenkins MCP Server - Connection Diagnostic")
+    print("=" * 60)
+    
+    success = test_connection()
+    sys.exit(0 if success else 1)
+```
+
+#### Run the Test
+
+```bash
+# Connect to VPN first
+# Then run:
+cd /path/to/jenkins_mcp_server
+source .venv/bin/activate
+python test_jenkins_connection.py
+```
+
+**Expected output if everything works:**
+```
+============================================================
+Jenkins MCP Server - Connection Diagnostic
+============================================================
+
+[Test 1] Testing DNS resolution...
+  ✓ DNS resolved: jenkins.example.com -> 10.0.0.1
+
+[Test 2] Testing basic HTTP connectivity...
+  ✓ Connection successful (no auth): 200 in 0.45s
+
+[Test 3] Testing authenticated request...
+  ✓ Authenticated request: 200 in 0.52s
+  ✓ Jenkins version: 2.401.3
+  ✓ Number of jobs: 42
+
+[Test 4] Testing python-jenkins library...
+  ✓ python-jenkins connection: John Doe in 0.38s
+
+✓ All tests passed! Jenkins MCP Server should work.
+```
+
+If all tests pass but MCP still fails, use Solution 2 (Direct Python Execution).
+
+---
+
+### 🆘 Still Having Issues?
+
+If you're still experiencing problems after trying the solutions above:
+
+1. **Check Claude Desktop logs:**
+   - **macOS**: `~/Library/Logs/Claude/mcp-server-jenkins.log`
+   - **Windows**: `%APPDATA%\Claude\logs\mcp-server-jenkins.log`
+   - **Linux**: `~/.config/Claude/logs/mcp-server-jenkins.log`
+
+2. **Enable verbose logging** by adding `--verbose` to args:
+   ```json
+   "args": [
+     "-m",
+     "jenkins_mcp_server",
+     "--env-file",
+     "/path/to/.env",
+     "--verbose"
+   ]
+   ```
+
+3. **Verify VPN is active** before starting Claude Desktop:
+   ```bash
+   # Test if you can reach your Jenkins server
+   curl -I http://your-jenkins-server:8080
+   ```
+
+4. **Check if other tools can reach Jenkins** while on VPN:
+   - Try accessing Jenkins in your browser
+   - Try `curl` from terminal
+   - If both work but MCP doesn't, use Solution 2
+
+5. **Open an issue** with:
+   - Your operating system
+   - Claude Desktop log file
+   - Output of the connection test script
+   - Your configuration (with credentials redacted)
+
+---
+
 ### Enable Debug Logging
 
 Run with verbose flag to see detailed logs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rishibhushan/jenkins-mcp-server",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "AI-enabled Jenkins automation via Model Context Protocol (MCP)",
   "main": "bin/jenkins-mcp.js",
   "bin": {

package/requirements.txt

@@ -2,6 +2,7 @@
 mcp>=1.0.0
 python-jenkins>=1.8.0
 requests>=2.28.0
+structlog>=23.1.0
 
 # Settings management
 pydantic>=2.0.0