@rishibhushan/jenkins-mcp-server 1.0.6 → 1.1.0

package/src/jenkins_mcp_server/__init__.py

@@ -14,19 +14,27 @@ from . import server
 
 
 def setup_logging(verbose: bool = False) -> None:
-    """Configure logging for the application"""
-    level = logging.DEBUG if verbose else logging.INFO
-
-    logging.basicConfig(
-        level=level,
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-        stream=sys.stderr
+    """Configure structured logging"""
+    import structlog
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            structlog.stdlib.filter_by_level,
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.processors.JSONRenderer() if not verbose else structlog.dev.ConsoleRenderer()
+        ],
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
     )
 
-    # Reduce noise from libraries
-    logging.getLogger('urllib3').setLevel(logging.WARNING)
-    logging.getLogger('requests').setLevel(logging.WARNING)
-
 
 def main():
     """

package/src/jenkins_mcp_server/cache.py

@@ -0,0 +1,310 @@
+"""
+Caching Module for Jenkins MCP Server
+
+Provides TTL-based caching for frequently accessed Jenkins data
+to reduce API calls and improve performance.
+"""
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+
+@dataclass
+class CachedData:
+    """Container for cached data with expiration"""
+    data: Any
+    cached_at: float
+    ttl_seconds: int
+    key: str
+    
+    def is_expired(self) -> bool:
+        """Check if cached data has expired"""
+        age = time.time() - self.cached_at
+        return age >= self.ttl_seconds
+    
+    def age_seconds(self) -> float:
+        """Get age of cached data in seconds"""
+        return time.time() - self.cached_at
+    
+    def time_until_expiry(self) -> float:
+        """Get seconds until expiry (negative if expired)"""
+        return self.ttl_seconds - self.age_seconds()
+
+
+class CacheManager:
+    """
+    Thread-safe cache manager with TTL support.
+    
+    Features:
+    - TTL-based expiration
+    - Thread-safe operations with async locks
+    - Cache statistics
+    - Automatic cleanup of expired entries
+    """
+    
+    def __init__(self):
+        """Initialize cache manager"""
+        self._cache: Dict[str, CachedData] = {}
+        self._lock = asyncio.Lock()
+        
+        # Statistics
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+        
+        logger.info("Cache manager initialized")
+    
+    async def get(self, key: str) -> Optional[Any]:
+        """
+        Get cached data if available and not expired.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            Cached data if available and valid, None otherwise
+        """
+        async with self._lock:
+            if key not in self._cache:
+                self._misses += 1
+                logger.debug(f"Cache miss: {key}")
+                return None
+            
+            cached = self._cache[key]
+            
+            if cached.is_expired():
+                # Remove expired entry
+                del self._cache[key]
+                self._evictions += 1
+                self._misses += 1
+                logger.debug(f"Cache expired: {key} (age: {cached.age_seconds():.1f}s)")
+                return None
+            
+            self._hits += 1
+            logger.debug(f"Cache hit: {key} (age: {cached.age_seconds():.1f}s, ttl: {cached.ttl_seconds}s)")
+            return cached.data
+    
+    async def set(self, key: str, data: Any, ttl_seconds: int = 30) -> None:
+        """
+        Store data in cache with TTL.
+        
+        Args:
+            key: Cache key
+            data: Data to cache
+            ttl_seconds: Time-to-live in seconds
+        """
+        async with self._lock:
+            self._cache[key] = CachedData(
+                data=data,
+                cached_at=time.time(),
+                ttl_seconds=ttl_seconds,
+                key=key
+            )
+            logger.debug(f"Cached: {key} (ttl: {ttl_seconds}s)")
+    
+    async def invalidate(self, key: str) -> bool:
+        """
+        Invalidate (remove) a specific cache entry.
+        
+        Args:
+            key: Cache key to invalidate
+            
+        Returns:
+            True if key was in cache, False otherwise
+        """
+        async with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                self._evictions += 1
+                logger.debug(f"Invalidated: {key}")
+                return True
+            return False
+    
+    async def invalidate_pattern(self, pattern: str) -> int:
+        """
+        Invalidate all cache entries matching a pattern.
+        
+        Args:
+            pattern: String pattern to match (substring match)
+            
+        Returns:
+            Number of entries invalidated
+        """
+        async with self._lock:
+            keys_to_remove = [
+                key for key in self._cache.keys()
+                if pattern in key
+            ]
+            
+            for key in keys_to_remove:
+                del self._cache[key]
+                self._evictions += 1
+            
+            if keys_to_remove:
+                logger.debug(f"Invalidated {len(keys_to_remove)} entries matching '{pattern}'")
+            
+            return len(keys_to_remove)
+    
+    async def clear(self) -> int:
+        """
+        Clear all cached data.
+        
+        Returns:
+            Number of entries cleared
+        """
+        async with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            self._evictions += count
+            logger.info(f"Cache cleared: {count} entries removed")
+            return count
+    
+    async def cleanup_expired(self) -> int:
+        """
+        Remove all expired entries from cache.
+        
+        Returns:
+            Number of expired entries removed
+        """
+        async with self._lock:
+            expired_keys = [
+                key for key, cached in self._cache.items()
+                if cached.is_expired()
+            ]
+            
+            for key in expired_keys:
+                del self._cache[key]
+                self._evictions += 1
+            
+            if expired_keys:
+                logger.debug(f"Cleaned up {len(expired_keys)} expired entries")
+            
+            return len(expired_keys)
+    
+    async def get_or_fetch(
+        self,
+        key: str,
+        fetch_func: Callable[[], Any],
+        ttl_seconds: int = 30
+    ) -> Any:
+        """
+        Get cached data or fetch and cache if not available.
+        
+        Args:
+            key: Cache key
+            fetch_func: Function to call to fetch data if not cached
+            ttl_seconds: TTL for newly cached data
+            
+        Returns:
+            Cached or freshly fetched data
+        """
+        # Try cache first
+        cached_data = await self.get(key)
+        if cached_data is not None:
+            return cached_data
+        
+        # Fetch and cache
+        data = fetch_func()
+        await self.set(key, data, ttl_seconds)
+        return data
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dictionary with cache statistics
+        """
+        total_requests = self._hits + self._misses
+        hit_rate = (self._hits / total_requests * 100) if total_requests > 0 else 0
+        
+        return {
+            "size": len(self._cache),
+            "hits": self._hits,
+            "misses": self._misses,
+            "evictions": self._evictions,
+            "total_requests": total_requests,
+            "hit_rate_percent": round(hit_rate, 2)
+        }
+    
+    def reset_stats(self) -> None:
+        """Reset cache statistics"""
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+        logger.debug("Cache statistics reset")
+    
+    async def get_all_keys(self) -> list[str]:
+        """Get all cache keys"""
+        async with self._lock:
+            return list(self._cache.keys())
+    
+    async def get_cache_info(self) -> Dict[str, Any]:
+        """
+        Get detailed cache information.
+        
+        Returns:
+            Dictionary with cache details including per-entry info
+        """
+        async with self._lock:
+            entries = []
+            for key, cached in self._cache.items():
+                entries.append({
+                    "key": key,
+                    "age_seconds": round(cached.age_seconds(), 2),
+                    "ttl_seconds": cached.ttl_seconds,
+                    "expires_in_seconds": round(cached.time_until_expiry(), 2),
+                    "is_expired": cached.is_expired(),
+                    "cached_at": datetime.fromtimestamp(cached.cached_at).isoformat()
+                })
+            
+            return {
+                "stats": self.get_stats(),
+                "entries": entries
+            }
+
+
+# Global cache manager instance
+_cache_manager: Optional[CacheManager] = None
+
+
+def get_cache_manager() -> CacheManager:
+    """Get or create the global cache manager instance"""
+    global _cache_manager
+    if _cache_manager is None:
+        _cache_manager = CacheManager()
+    return _cache_manager
+
+
+# Convenience functions
+async def get_cached(key: str) -> Optional[Any]:
+    """Get cached data"""
+    return await get_cache_manager().get(key)
+
+
+async def set_cached(key: str, data: Any, ttl_seconds: int = 30) -> None:
+    """Set cached data"""
+    await get_cache_manager().set(key, data, ttl_seconds)
+
+
+async def invalidate_cache(key: str) -> bool:
+    """Invalidate cache entry"""
+    return await get_cache_manager().invalidate(key)
+
+
+async def clear_cache() -> int:
+    """Clear all cache"""
+    return await get_cache_manager().clear()
+
+
+async def get_cache_stats() -> Dict[str, Any]:
+    """Get cache statistics"""
+    return get_cache_manager().get_stats()

package/src/jenkins_mcp_server/config.py

@@ -5,6 +5,8 @@ Handles loading Jenkins connection settings from multiple sources:
 1. VS Code settings.json (highest priority)
 2. Environment variables / .env file
 3. Direct instantiation with parameters
+
+Enhanced with timeout configuration support.
 """
 
 import json
@@ -50,6 +52,50 @@ class JenkinsSettings(BaseSettings):
         description="Jenkins API token (preferred over password)"
     )
 
+    # Timeout settings (High Priority Issue #4)
+    timeout: int = Field(
+        default=30,
+        description="Default timeout for Jenkins API calls in seconds",
+        ge=5,
+        le=300
+    )
+
+    connect_timeout: int = Field(
+        default=10,
+        description="Connection timeout in seconds",
+        ge=2,
+        le=60
+    )
+
+    read_timeout: int = Field(
+        default=30,
+        description="Read timeout for API responses in seconds",
+        ge=5,
+        le=300
+    )
+
+    # Retry settings
+    max_retries: int = Field(
+        default=3,
+        description="Maximum number of retry attempts for failed requests",
+        ge=0,
+        le=10
+    )
+
+    # Console output settings (High Priority Issue #5)
+    console_max_lines: int = Field(
+        default=1000,
+        description="Default maximum lines to return from console output",
+        ge=10,
+        le=50000
+    )
+
+    # SSL verification
+    verify_ssl: bool = Field(
+        default=True,
+        description="Whether to verify SSL certificates"
+    )
+
     model_config = SettingsConfigDict(
         env_prefix="JENKINS_",
         env_file_encoding="utf-8",
@@ -92,6 +138,12 @@ class JenkinsSettings(BaseSettings):
         logger.info("Jenkins Configuration:")
         logger.info(f"  URL: {self.url or 'Not configured'}")
         logger.info(f"  Username: {self.username or 'Not configured'}")
+        logger.info(f"  Timeout: {self.timeout}s")
+        logger.info(f"  Connect Timeout: {self.connect_timeout}s")
+        logger.info(f"  Read Timeout: {self.read_timeout}s")
+        logger.info(f"  Max Retries: {self.max_retries}")
+        logger.info(f"  Console Max Lines: {self.console_max_lines}")
+        logger.info(f"  Verify SSL: {self.verify_ssl}")
 
         if hide_sensitive:
             logger.info(f"  Authentication: {self.auth_method}")
@@ -244,7 +296,8 @@ def load_settings(
         print(f"=== VS Code settings loaded: {vscode_settings is not None} ===", file=sys.stderr, flush=True)
         if vscode_settings:
             # Merge VS Code settings into our settings object
-            for key in ['url', 'username', 'password', 'token']:
+            for key in ['url', 'username', 'password', 'token', 'timeout', 'connect_timeout',
+                        'read_timeout', 'max_retries', 'console_max_lines', 'verify_ssl']:
                 vscode_value = vscode_settings.get(key)
                 if vscode_value is not None:
                     setattr(settings, key, vscode_value)

package/src/jenkins_mcp_server/jenkins_client.py

@@ -3,6 +3,8 @@ Jenkins MCP Server Client Module
 
 Provides a clean interface to Jenkins API operations with automatic fallback
 between python-jenkins library and direct REST API calls.
+
+Enhanced with configurable timeout support.
 """
 
 import logging
@@ -34,7 +36,8 @@ class JenkinsClient:
     Client for interacting with Jenkins API.
 
     Supports both python-jenkins library and direct REST API calls
-    with automatic fallback for reliability.
+    with automatic fallback for reliability. Enhanced with configurable
+    timeout support.
     """
 
     def __init__(self, settings: Optional[JenkinsSettings] = None):
@@ -60,6 +63,12 @@ class JenkinsClient:
         username, auth_value = self.settings.get_credentials()
         self.auth = HTTPBasicAuth(username, auth_value)
 
+        # Store timeout settings (High Priority Issue #4)
+        self.timeout = self.settings.timeout
+        self.connect_timeout = self.settings.connect_timeout
+        self.read_timeout = self.settings.read_timeout
+        self.verify_ssl = self.settings.verify_ssl
+
         # Cache for python-jenkins server instance
         self._server: Optional[jenkins.Jenkins] = None
 
@@ -67,14 +76,14 @@ class JenkinsClient:
         self._test_connection()
 
     def _test_connection(self) -> None:
-        """Test connection to Jenkins server (with quick timeout for MCP)"""
+        """Test connection to Jenkins server (with configurable timeout)"""
         try:
-            # Quick connection test with short timeout for MCP compatibility
+            # Quick connection test with configured timeout for MCP compatibility
             response = requests.get(
                 f"{self.base_url}/api/json",
                 auth=self.auth,
-                verify=False,
-                timeout=3  # Short timeout for responsiveness
+                verify=self.verify_ssl if self.verify_ssl else False,
+                timeout=self.connect_timeout  # Use configured connect timeout
             )
             response.raise_for_status()
 
@@ -83,7 +92,7 @@ class JenkinsClient:
             logger.debug(f"Jenkins version: {data.get('_class', 'unknown')}")
 
         except requests.Timeout:
-            logger.warning(f"Connection to Jenkins timed out (server may be slow)")
+            logger.warning(f"Connection to Jenkins timed out after {self.connect_timeout}s (server may be slow)")
             # Don't fail - let actual operations fail if there's a real problem
         except requests.RequestException as e:
             logger.warning(f"Could not verify Jenkins connection: {e}")
@@ -91,19 +100,20 @@ class JenkinsClient:
 
     @property
     def server(self) -> jenkins.Jenkins:
-        """Get or create python-jenkins server instance (lazy initialization)"""
+        """Get or create python-jenkins server instance (lazy initialization with timeout)"""
         if self._server is None:
             username, password = self.settings.get_credentials()
             self._server = jenkins.Jenkins(
                 self.base_url,
                 username=username,
-                password=password
+                password=password,
+                timeout=self.timeout  # Use configured timeout
             )
         return self._server
 
     def _api_call(self, method: str, endpoint: str, **kwargs) -> requests.Response:
         """
-        Make a direct REST API call to Jenkins.
+        Make a direct REST API call to Jenkins with configured timeout.
 
         Args:
             method: HTTP method (GET, POST, etc.)
@@ -115,8 +125,11 @@ class JenkinsClient:
         """
         url = f"{self.base_url}{endpoint}"
         kwargs.setdefault('auth', self.auth)
-        kwargs.setdefault('verify', False)
-        kwargs.setdefault('timeout', 30)
+        kwargs.setdefault('verify', self.verify_ssl if self.verify_ssl else False)
+
+        # Use configured timeout (can be overridden per call)
+        if 'timeout' not in kwargs:
+            kwargs['timeout'] = (self.connect_timeout, self.read_timeout)
 
         response = requests.request(method, url, **kwargs)
         response.raise_for_status()
@@ -220,82 +233,46 @@ class JenkinsClient:
         Returns:
             Dict with 'queue_id' and 'build_number' (if wait_for_start=True)
         """
-        try:
-            # Trigger build using python-jenkins
-            queue_id = self.server.build_job(job_name, parameters or {})
-            queue_id = int(queue_id) if queue_id else None
-
-            build_number = None
-            if wait_for_start and queue_id:
-                build_number = self._wait_for_build_start(
-                    queue_id, timeout, poll_interval
-                )
-
-            return {"queue_id": queue_id, "build_number": build_number}
+        # Get the last build number before triggering
+        last_build_num = self.get_last_build_number(job_name) or 0
 
-        except Exception as e:
-            logger.debug(f"python-jenkins failed, using REST API: {e}")
-            return self._build_job_rest(
-                job_name, parameters, wait_for_start, timeout, poll_interval
+        # Trigger the build
+        if parameters:
+            self._api_call(
+                'POST',
+                f'/job/{job_name}/buildWithParameters',
+                params=parameters
             )
+        else:
+            self._api_call('POST', f'/job/{job_name}/build')
 
-    def _build_job_rest(
-            self,
-            job_name: str,
-            parameters: Optional[Dict[str, Any]],
-            wait_for_start: bool,
-            timeout: int,
-            poll_interval: float
-    ) -> Dict[str, Optional[int]]:
-        """Build job using REST API (fallback method)"""
-        endpoint = f'/job/{job_name}/buildWithParameters' if parameters else f'/job/{job_name}/build'
-
-        response = self._api_call('POST', endpoint, params=parameters)
+        # Get queue ID from response
+        queue_id = self._extract_queue_id_from_location(
+            f'/job/{job_name}/build'
+        )
 
-        # Extract queue ID from Location header
-        location = response.headers.get('Location', '')
-        queue_id = self._extract_queue_id(location)
+        result = {
+            'queue_id': queue_id,
+            'build_number': None
+        }
 
-        build_number = None
-        if wait_for_start and queue_id:
-            build_number = self._wait_for_build_start(queue_id, timeout, poll_interval)
+        # Optionally wait for build to start
+        if wait_for_start:
+            start_time = time.time()
+            while time.time() - start_time < timeout:
+                time.sleep(poll_interval)
 
-        return {"queue_id": queue_id, "build_number": build_number}
+                # Check if a new build has started
+                current_build_num = self.get_last_build_number(job_name)
+                if current_build_num and current_build_num > last_build_num:
+                    result['build_number'] = current_build_num
+                    logger.info(f"Build {job_name} #{current_build_num} started")
+                    break
 
-    def _wait_for_build_start(
-            self,
-            queue_id: int,
-            timeout: int,
-            poll_interval: float
-    ) -> Optional[int]:
-        """Wait for a queued build to start and return its build number"""
-        elapsed = 0.0
-
-        while elapsed < timeout:
-            try:
-                # Try python-jenkins first
-                item = self.server.get_queue_item(queue_id)
-                if item and item.get('executable'):
-                    return int(item['executable']['number'])
-            except Exception:
-                # Fall back to REST API
-                try:
-                    response = self._api_call('GET', f'/queue/item/{queue_id}/api/json')
-                    item = response.json()
-                    if item.get('executable'):
-                        return int(item['executable']['number'])
-                except Exception:
-                    pass
-
-            time.sleep(poll_interval)
-            elapsed += poll_interval
-
-        logger.warning(f"Timeout waiting for build {queue_id} to start")
-        return None
+        return result
 
-    @staticmethod
-    def _extract_queue_id(location: str) -> Optional[int]:
-        """Extract queue ID from Jenkins Location header"""
+    def _extract_queue_id_from_location(self, location: str) -> Optional[int]:
+        """Extract queue ID from Location header"""
         if not location:
             return None
 
@@ -480,6 +457,18 @@ class JenkinsClient:
         response = self._api_call('GET', f'/computer/{node_name}/api/json')
         return response.json()
 
+    # ==================== Additional Helper Methods ====================
+
+    def get_whoami(self) -> Dict[str, Any]:
+        """Get information about the current authenticated user"""
+        response = self._api_call('GET', '/me/api/json')
+        return response.json()
+
+    def get_version(self) -> str:
+        """Get Jenkins version"""
+        response = self._api_call('GET', '/api/json')
+        return response.headers.get('X-Jenkins', 'Unknown')
+
 
 # ==================== Client Factory ====================
 
@@ -515,4 +504,4 @@ def get_jenkins_client(settings: Optional[JenkinsSettings] = None) -> JenkinsCli
 def reset_default_client() -> None:
     """Reset the default client (useful for testing or reconfiguration)"""
     global _default_client
-    _default_client = None
+    _default_client = None