rootly-mcp-server 2.0.10__py3-none-any.whl → 2.0.11__py3-none-any.whl

rootly_mcp_server/smart_utils.py

@@ -0,0 +1,398 @@
+"""
+Smart utility functions for AI-powered incident analysis.
+
+This module provides text similarity, pattern matching, and intelligent analysis
+functions for implementing smart incident management features.
+"""
+
+import re
+import logging
+from typing import List, Dict, Optional, Any
+from dataclasses import dataclass
+from datetime import datetime
+
+# Check ML library availability
+import importlib.util
+ML_AVAILABLE = (
+    importlib.util.find_spec("sklearn.feature_extraction.text") is not None and
+    importlib.util.find_spec("sklearn.metrics.pairwise") is not None
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class IncidentSimilarity:
+    """Represents similarity between two incidents."""
+    incident_id: str
+    title: str
+    similarity_score: float
+    matched_services: List[str]
+    matched_keywords: List[str]
+    resolution_summary: str = ""
+    resolution_time_hours: Optional[float] = None
+
+
+class TextSimilarityAnalyzer:
+    """Analyzes text similarity between incidents using TF-IDF and cosine similarity."""
+    
+    def __init__(self):
+        if not ML_AVAILABLE:
+            logger.warning("scikit-learn not available. Text similarity will use basic keyword matching.")
+        self.vectorizer = None
+        self.incident_vectors = None
+        self.incident_metadata = {}
+    
+    def preprocess_text(self, text: Optional[str]) -> str:
+        """Clean and normalize text for analysis."""
+        if not text:
+            return ""
+        
+        # Convert to lowercase
+        text = text.lower()
+        
+        # Remove special characters but keep spaces and important symbols
+        text = re.sub(r'[^\w\s\-\.]', ' ', text)
+        
+        # Replace multiple spaces with single space
+        text = re.sub(r'\s+', ' ', text)
+        
+        # Remove common stopwords manually (basic set)
+        stopwords = {'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'is', 'are', 'was', 'were'}
+        words = text.split()
+        text = ' '.join([word for word in words if word not in stopwords and len(word) > 1])
+        
+        return text.strip()
+    
+    def extract_services(self, text: str) -> List[str]:
+        """Extract service names from incident text."""
+        services = []
+        
+        # Common service patterns
+        service_patterns = [
+            r'\b(\w+)-(?:service|api|app|server|db)\b',  # service-api, auth-service
+            r'\b(\w+)(?:service|api|app|server|db)\b',   # paymentapi, authservice
+            r'\b(\w+)\.(?:service|api|app|com)\b',       # auth.service, api.com
+        ]
+        
+        text_lower = text.lower()
+        for pattern in service_patterns:
+            matches = re.findall(pattern, text_lower)
+            services.extend(matches)
+        
+        # Remove duplicates while preserving order
+        return list(dict.fromkeys(services))
+    
+    def extract_error_patterns(self, text: str) -> List[str]:
+        """Extract common error patterns from incident text."""
+        patterns = []
+        
+        # HTTP status codes
+        http_codes = re.findall(r'\b[45]\d\d\b', text)
+        patterns.extend([f"http-{code}" for code in http_codes])
+        
+        # Database errors
+        if re.search(r'\b(?:connection|timeout|database|db)\b', text.lower()):
+            patterns.append("database-error")
+        
+        # Memory/resource errors  
+        if re.search(r'\b(?:memory|cpu|disk|resource)\b', text.lower()):
+            patterns.append("resource-error")
+            
+        # Network errors
+        if re.search(r'\b(?:network|dns|connection|unreachable)\b', text.lower()):
+            patterns.append("network-error")
+        
+        return patterns
+    
+    def calculate_similarity(self, incidents: List[Dict], target_incident: Dict) -> List[IncidentSimilarity]:
+        """Calculate similarity scores between target incident and historical incidents."""
+        if not incidents:
+            return []
+        
+        target_text = self._combine_incident_text(target_incident)
+        target_services = self.extract_services(target_text)
+        target_errors = self.extract_error_patterns(target_text)
+        
+        similarities = []
+        
+        if ML_AVAILABLE and len(incidents) > 1:
+            similarities = self._calculate_tfidf_similarity(incidents, target_incident, target_text, target_services, target_errors)
+        else:
+            similarities = self._calculate_keyword_similarity(incidents, target_incident, target_text, target_services, target_errors)
+        
+        # Sort by similarity score descending
+        return sorted(similarities, key=lambda x: x.similarity_score, reverse=True)
+    
+    def _combine_incident_text(self, incident: Dict) -> str:
+        """Combine incident title, description, and other text fields."""
+        text_parts = []
+        
+        # Get text from incident attributes
+        attributes = incident.get('attributes', {})
+        text_parts.append(attributes.get('title', ''))
+        text_parts.append(attributes.get('summary', ''))
+        text_parts.append(attributes.get('description', ''))
+        
+        # Also check root level for backward compatibility
+        text_parts.append(incident.get('title', ''))
+        text_parts.append(incident.get('summary', ''))
+        text_parts.append(incident.get('description', ''))
+        
+        combined = ' '.join([part for part in text_parts if part])
+        return self.preprocess_text(combined)
+    
+    def _calculate_tfidf_similarity(self, incidents: List[Dict], target_incident: Dict, 
+                                  target_text: str, target_services: List[str], 
+                                  target_errors: List[str]) -> List[IncidentSimilarity]:
+        """Use TF-IDF and cosine similarity for advanced text matching."""
+        if not ML_AVAILABLE:
+            return []
+            
+        # Import here to avoid issues with conditional imports
+        from sklearn.feature_extraction.text import TfidfVectorizer
+        from sklearn.metrics.pairwise import cosine_similarity
+        
+        # Prepare texts
+        incident_texts = [self._combine_incident_text(inc) for inc in incidents]
+        all_texts = incident_texts + [target_text]
+        
+        # Vectorize
+        vectorizer = TfidfVectorizer(max_features=1000, ngram_range=(1, 2))
+        tfidf_matrix = vectorizer.fit_transform(all_texts)
+        
+        # Calculate similarities
+        target_vector = tfidf_matrix[-1]
+        similarities = cosine_similarity(target_vector, tfidf_matrix[:-1]).flatten()
+        
+        results = []
+        for i, incident in enumerate(incidents):
+            if similarities[i] > 0.1:  # Only include reasonable matches
+                incident_services = self.extract_services(incident_texts[i])
+                incident_errors = self.extract_error_patterns(incident_texts[i])
+                
+                # Bonus for matching services and error patterns
+                service_bonus = len(set(target_services) & set(incident_services)) * 0.1
+                error_bonus = len(set(target_errors) & set(incident_errors)) * 0.15
+                
+                final_score = min(1.0, similarities[i] + service_bonus + error_bonus)
+                
+                results.append(IncidentSimilarity(
+                    incident_id=str(incident.get('id', '')),
+                    title=incident.get('attributes', {}).get('title', 'Unknown'),
+                    similarity_score=final_score,
+                    matched_services=list(set(target_services) & set(incident_services)),
+                    matched_keywords=self._extract_common_keywords(target_text, incident_texts[i]),
+                    resolution_summary=incident.get('attributes', {}).get('summary', ''),
+                    resolution_time_hours=self._calculate_resolution_time(incident)
+                ))
+        
+        return results
+    
+    def _calculate_keyword_similarity(self, incidents: List[Dict], target_incident: Dict,
+                                    target_text: str, target_services: List[str], 
+                                    target_errors: List[str]) -> List[IncidentSimilarity]:
+        """Fallback keyword-based similarity when ML libraries not available."""
+        target_words = set(target_text.split())
+        
+        results = []
+        for incident in incidents:
+            incident_text = self._combine_incident_text(incident)
+            incident_words = set(incident_text.split())
+            incident_services = self.extract_services(incident_text)
+            incident_errors = self.extract_error_patterns(incident_text)
+            
+            # Calculate Jaccard similarity
+            if len(target_words | incident_words) > 0:
+                word_similarity = len(target_words & incident_words) / len(target_words | incident_words)
+            else:
+                word_similarity = 0
+            
+            # Service and error pattern bonuses
+            service_bonus = len(set(target_services) & set(incident_services)) * 0.2
+            error_bonus = len(set(target_errors) & set(incident_errors)) * 0.25
+            
+            final_score = min(1.0, word_similarity + service_bonus + error_bonus)
+            
+            if final_score > 0.15:  # Only include reasonable matches
+                results.append(IncidentSimilarity(
+                    incident_id=str(incident.get('id', '')),
+                    title=incident.get('attributes', {}).get('title', 'Unknown'),
+                    similarity_score=final_score,
+                    matched_services=list(set(target_services) & set(incident_services)),
+                    matched_keywords=list(target_words & incident_words)[:5],  # Top 5 matches
+                    resolution_summary=incident.get('attributes', {}).get('summary', ''),
+                    resolution_time_hours=self._calculate_resolution_time(incident)
+                ))
+        
+        return results
+    
+    def _extract_common_keywords(self, text1: str, text2: str) -> List[str]:
+        """Extract common meaningful keywords between two texts."""
+        words1 = set(text1.split())
+        words2 = set(text2.split())
+        common = words1 & words2
+        
+        # Filter out very short words and return top matches
+        meaningful = [word for word in common if len(word) > 2]
+        return meaningful[:5]
+    
+    def _calculate_resolution_time(self, incident: Dict) -> Optional[float]:
+        """Calculate resolution time in hours if timestamps are available."""
+        try:
+            attributes = incident.get('attributes', {})
+            created_at = attributes.get('created_at')
+            resolved_at = attributes.get('resolved_at') or attributes.get('updated_at')
+            
+            if created_at and resolved_at:
+                # Try to parse ISO format timestamps
+                created = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                resolved = datetime.fromisoformat(resolved_at.replace('Z', '+00:00'))
+                diff = resolved - created
+                return diff.total_seconds() / 3600  # Convert to hours
+        except Exception:
+            pass
+        
+        return None
+
+
+class SolutionExtractor:
+    """Extract and format solution information from resolved incidents."""
+    
+    def extract_solutions(self, similar_incidents: List[IncidentSimilarity]) -> Dict[str, Any]:
+        """Extract actionable solutions from similar resolved incidents."""
+        if not similar_incidents:
+            return {
+                "solutions": [],
+                "common_patterns": [],
+                "average_resolution_time": None,
+                "total_similar_incidents": 0
+            }
+        
+        solutions = []
+        resolution_times = []
+        all_keywords = []
+        
+        for incident in similar_incidents[:5]:  # Top 5 most similar
+            solution_info = {
+                "incident_id": incident.incident_id,
+                "title": incident.title,
+                "similarity": round(incident.similarity_score, 3),
+                "matched_services": incident.matched_services,
+                "resolution_summary": incident.resolution_summary or "No resolution summary available",
+                "resolution_time_hours": incident.resolution_time_hours
+            }
+            
+            # Extract potential solution steps from resolution summary
+            solution_steps = self._extract_action_items(incident.resolution_summary)
+            if solution_steps:
+                solution_info["suggested_actions"] = solution_steps
+            
+            solutions.append(solution_info)
+            
+            if incident.resolution_time_hours:
+                resolution_times.append(incident.resolution_time_hours)
+            
+            all_keywords.extend(incident.matched_keywords)
+        
+        # Calculate average resolution time
+        avg_resolution = sum(resolution_times) / len(resolution_times) if resolution_times else None
+        
+        # Find common patterns
+        common_patterns = self._identify_common_patterns(all_keywords, similar_incidents)
+        
+        return {
+            "solutions": solutions,
+            "common_patterns": common_patterns,
+            "average_resolution_time": round(avg_resolution, 2) if avg_resolution else None,
+            "total_similar_incidents": len(similar_incidents)
+        }
+    
+    def _extract_action_items(self, resolution_text: str) -> List[str]:
+        """Extract potential action items from resolution text."""
+        if not resolution_text:
+            return []
+        
+        actions = []
+        text_lower = resolution_text.lower()
+        
+        # Look for common action patterns
+        action_patterns = [
+            r'restart(?:ed)?\s+(\w+(?:\s+\w+)*)',
+            r'clear(?:ed)?\s+(\w+(?:\s+\w+)*)',
+            r'update(?:d)?\s+(\w+(?:\s+\w+)*)',
+            r'fix(?:ed)?\s+(\w+(?:\s+\w+)*)',
+            r'roll(?:ed)?\s+back\s+(\w+(?:\s+\w+)*)',
+            r'scale(?:d)?\s+(\w+(?:\s+\w+)*)',
+            r'deploy(?:ed)?\s+(\w+(?:\s+\w+)*)',
+        ]
+        
+        for pattern in action_patterns:
+            matches = re.findall(pattern, text_lower)
+            for match in matches:
+                # Extract the base action word from the pattern
+                if 'roll' in pattern and 'back' in pattern:
+                    action = f"rollback {match}".strip()
+                elif 'restart' in pattern:
+                    action = f"restart {match}".strip()
+                elif 'clear' in pattern:
+                    action = f"clear {match}".strip()
+                elif 'update' in pattern:
+                    action = f"update {match}".strip()
+                elif 'fix' in pattern:
+                    action = f"fix {match}".strip()
+                elif 'scale' in pattern:
+                    action = f"scale {match}".strip()
+                elif 'deploy' in pattern:
+                    action = f"deploy {match}".strip()
+                else:
+                    # Fallback to original logic
+                    base_pattern = pattern.split('(')[0].replace('(?:ed)?', '').replace('(?:d)?', '')
+                    action = f"{base_pattern.replace(r'\s+', ' ')} {match}".strip()
+                actions.append(action)
+        
+        # Look for explicit steps
+        if 'step' in text_lower or 'action' in text_lower:
+            sentences = resolution_text.split('.')
+            for sentence in sentences:
+                if any(word in sentence.lower() for word in ['step', 'action', 'fix', 'solution']):
+                    actions.append(sentence.strip())
+        
+        return actions[:5]  # Limit to top 5 actions
+    
+    def _identify_common_patterns(self, keywords: List[str], incidents: List[IncidentSimilarity]) -> List[str]:
+        """Identify common patterns across similar incidents."""
+        patterns = []
+        
+        # Service patterns
+        all_services = []
+        for incident in incidents:
+            all_services.extend(incident.matched_services)
+        
+        if all_services:
+            common_services = [service for service in set(all_services) if all_services.count(service) >= 2]
+            if common_services:
+                patterns.append(f"Common services affected: {', '.join(common_services)}")
+        
+        # Keyword patterns
+        if keywords:
+            keyword_counts = {}
+            for keyword in keywords:
+                keyword_counts[keyword] = keyword_counts.get(keyword, 0) + 1
+            
+            frequent_keywords = [k for k, v in keyword_counts.items() if v >= 2 and len(k) > 3]
+            if frequent_keywords:
+                patterns.append(f"Common keywords: {', '.join(frequent_keywords[:3])}")
+        
+        # Resolution time patterns
+        resolution_times = [inc.resolution_time_hours for inc in incidents if inc.resolution_time_hours is not None]
+        if resolution_times:
+            avg_time = sum(resolution_times) / len(resolution_times)
+            if avg_time < 1:
+                patterns.append("These incidents typically resolve quickly (< 1 hour)")
+            elif avg_time > 4:
+                patterns.append("These incidents typically take longer to resolve (> 4 hours)")
+            else:
+                patterns.append(f"These incidents typically resolve in {avg_time:.1f} hours")
+        
+        return patterns

{rootly_mcp_server-2.0.10.dist-info → rootly_mcp_server-2.0.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rootly-mcp-server
-Version: 2.0.10
+Version: 2.0.11
 Summary: A Model Context Protocol server for Rootly APIs using OpenAPI spec
 Project-URL: Homepage, https://github.com/Rootly-AI-Labs/Rootly-MCP-server
 Project-URL: Issues, https://github.com/Rootly-AI-Labs/Rootly-MCP-server/issues
@@ -17,8 +17,10 @@ Requires-Python: >=3.12
 Requires-Dist: brotli>=1.0.0
 Requires-Dist: fastmcp>=2.9.0
 Requires-Dist: httpx>=0.24.0
+Requires-Dist: numpy>=1.24.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.28.0
+Requires-Dist: scikit-learn>=1.3.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: isort>=5.0.0; extra == 'dev'
@@ -43,9 +45,7 @@ An MCP server for the [Rootly API](https://docs.rootly.com/api-reference/overvie
 
 ## Installation
 
-Install via our [PyPi package](https://pypi.org/project/rootly-mcp-server/) or by cloning this repository.
-
-Configure your MCP-compatible editor (tested with Cursor and Windsurf) with the following:
+Configure your MCP-compatible editor (tested with Cursor) with one of the configurations below. The package will be automatically downloaded and installed when you first open your editor.
 
 ### With uv
 
@@ -69,7 +69,7 @@ Configure your MCP-compatible editor (tested with Cursor and Windsurf) with the
 }
 ```
 
-### With uv-tool-uvx
+### With uvx
 
 ```json
 {
@@ -139,6 +139,11 @@ Alternatively, connect directly to our hosted MCP server:
 - **Dynamic Tool Generation**: Automatically creates MCP resources from Rootly's OpenAPI (Swagger) specification
 - **Smart Pagination**: Defaults to 10 items per request for incident endpoints to prevent context window overflow
 - **API Filtering**: Limits exposed API endpoints for security and performance
+- **AI-Powered Incident Analysis**: Smart tools that learn from historical incident data
+  - **`find_related_incidents`**: Uses TF-IDF similarity analysis to find historically similar incidents
+  - **`suggest_solutions`**: Mines past incident resolutions to recommend actionable solutions
+- **MCP Resources**: Exposes incident and team data as structured resources for easy AI reference
+- **Intelligent Pattern Recognition**: Automatically identifies services, error types, and resolution patterns
 
 ### Whitelisted Endpoints
 
@@ -180,10 +185,49 @@ By default, the following Rootly API endpoints are exposed to the AI agent (see
 We limit exposed API paths for two key reasons:
 
 1. **Context Management**: Rootly's comprehensive API can overwhelm AI agents, affecting their ability to perform simple tasks effectively
-2. **Security**: Control which information and actions are accessible through the MCP server
+2. **Security**: Controls which information and actions are accessible through the MCP server
 
 To expose additional paths, modify the `allowed_paths` variable in `src/rootly_mcp_server/server.py`.
 
+### AI-Powered Smart Tools
+
+The MCP server includes intelligent tools that analyze historical incident data to provide actionable insights:
+
+#### `find_related_incidents`
+Finds historically similar incidents using machine learning text analysis:
+```
+find_related_incidents(incident_id="12345", similarity_threshold=0.3, max_results=5)
+```
+- **Input**: Incident ID, similarity threshold (0.0-1.0), max results
+- **Output**: Similar incidents with confidence scores, matched services, and resolution times
+- **Use Case**: Get context from past incidents to understand patterns and solutions
+
+#### `suggest_solutions` 
+Recommends solutions by analyzing how similar incidents were resolved:
+```
+suggest_solutions(incident_id="12345", max_solutions=3)
+# OR for new incidents:
+suggest_solutions(incident_title="Payment API errors", incident_description="Users getting 500 errors during checkout")
+```
+- **Input**: Either incident ID OR title/description text
+- **Output**: Actionable solution recommendations with confidence scores and time estimates  
+- **Use Case**: Get AI-powered suggestions based on successful past resolutions
+
+#### How It Works
+- **Text Similarity**: Uses TF-IDF vectorization and cosine similarity (scikit-learn)
+- **Service Detection**: Automatically identifies affected services from incident text
+- **Pattern Recognition**: Finds common error types, resolution patterns, and time estimates
+- **Fallback Mode**: Works without ML libraries using keyword-based similarity
+- **Solution Mining**: Extracts actionable steps from resolution summaries
+
+#### Data Requirements
+For optimal results, ensure your Rootly incidents have descriptive:
+- **Titles**: Clear, specific incident descriptions
+- **Summaries**: Detailed resolution steps when closing incidents
+- **Service Tags**: Proper service identification
+
+Example good resolution summary: `"Restarted auth-service, cleared Redis cache, and increased connection pool from 10 to 50"`
+
 ## About Rootly AI Labs
 
 This project was developed by [Rootly AI Labs](https://labs.rootly.ai/), where we're building the future of system reliability and operational excellence. As an open-source incubator, we share ideas, experiment, and rapidly prototype solutions that benefit the entire community.
@@ -219,9 +263,7 @@ uv pip install <package>
 
 ### 3. Verify Installation
 
-Run the test client to ensure everything is configured correctly:
+The server should now be ready to use with your MCP-compatible editor.
 
-```bash
-python src/rootly_mcp_server/test_client.py
-```
+**For developers:** Additional testing tools are available in the `tests/` directory.
 

rootly_mcp_server-2.0.11.dist-info/RECORD

@@ -0,0 +1,12 @@
+rootly_mcp_server/__init__.py,sha256=6pLh19IFyqE-Cve9zergkD-X_yApEkInREKmRa73T6s,628
+rootly_mcp_server/__main__.py,sha256=_F4p65_VjnN84RtmEdESVLLH0tO5tL9qBfb2Xdvbj2E,6480
+rootly_mcp_server/client.py,sha256=uit-YijR7OAJtysBoclqnublEDVkFfcb29wSzhpBv44,4686
+rootly_mcp_server/server.py,sha256=5NyGWUOjz1C1kFbAbu2iMNfuKo53_Sq254vF0cEUSHE,41358
+rootly_mcp_server/smart_utils.py,sha256=B0to9o55PMwQPLFT6GZAg_S_Nt4pKFRQq0AXBL-GJp8,17442
+rootly_mcp_server/utils.py,sha256=NyxdcDiFGlV2a8eBO4lKgZg0D7Gxr6xUIB0YyJGgpPA,4165
+rootly_mcp_server/data/__init__.py,sha256=fO8a0bQnRVEoRMHKvhFzj10bhoaw7VsI51czc2MsUm4,143
+rootly_mcp_server-2.0.11.dist-info/METADATA,sha256=fGFaM6E_5DJ1gdvFfuw1yyNBeJZMLdsDM56gRnDhy38,8722
+rootly_mcp_server-2.0.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rootly_mcp_server-2.0.11.dist-info/entry_points.txt,sha256=NE33b8VgigVPGBkboyo6pvN1Vz35HZtLybxMO4Q03PI,70
+rootly_mcp_server-2.0.11.dist-info/licenses/LICENSE,sha256=c9w9ZZGl14r54tsP40oaq5adTVX_HMNHozPIH2ymzmw,11341
+rootly_mcp_server-2.0.11.dist-info/RECORD,,