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

rootly_mcp_server/client.py

@@ -121,7 +121,7 @@ class RootlyClient:
             # Add response details if available
             if hasattr(e, "response") and e.response is not None:
                 try:
-                    error_response["status_code"] = e.response.status_code
+                    error_response["status_code"] = str(e.response.status_code)
                     error_response["response_text"] = e.response.text
                 except Exception:
                     pass

rootly_mcp_server/server.py

@@ -19,13 +19,104 @@ from fastmcp import FastMCP
 from pydantic import Field
 
 from .utils import sanitize_parameters_in_spec
+from .smart_utils import TextSimilarityAnalyzer, SolutionExtractor
 
 # Set up logger
 logger = logging.getLogger(__name__)
 
+
+class MCPError:
+    """Enhanced error handling for MCP protocol compliance."""
+    
+    @staticmethod
+    def protocol_error(code: int, message: str, data: Optional[Dict] = None):
+        """Create a JSON-RPC protocol-level error response."""
+        error_response = {
+            "jsonrpc": "2.0",
+            "error": {
+                "code": code,
+                "message": message
+            }
+        }
+        if data:
+            error_response["error"]["data"] = data
+        return error_response
+    
+    @staticmethod
+    def tool_error(error_message: str, error_type: str = "execution_error", details: Optional[Dict] = None):
+        """Create a tool-level error response (returned as successful tool result)."""
+        error_response = {
+            "error": True,
+            "error_type": error_type,
+            "message": error_message
+        }
+        if details:
+            error_response["details"] = details
+        return error_response
+    
+    @staticmethod
+    def categorize_error(exception: Exception) -> tuple[str, str]:
+        """Categorize an exception into error type and appropriate message."""
+        error_str = str(exception)
+        exception_type = type(exception).__name__
+        
+        # Authentication/Authorization errors
+        if any(keyword in error_str.lower() for keyword in ["401", "unauthorized", "authentication", "token", "forbidden"]):
+            return "authentication_error", f"Authentication failed: {error_str}"
+        
+        # Network/Connection errors  
+        if any(keyword in exception_type.lower() for keyword in ["connection", "timeout", "network"]):
+            return "network_error", f"Network error: {error_str}"
+        
+        # HTTP errors
+        if "40" in error_str[:10]:  # 4xx client errors
+            return "client_error", f"Client error: {error_str}"
+        elif "50" in error_str[:10]:  # 5xx server errors
+            return "server_error", f"Server error: {error_str}"
+        
+        # Validation errors
+        if any(keyword in exception_type.lower() for keyword in ["validation", "pydantic", "field"]):
+            return "validation_error", f"Input validation error: {error_str}"
+            
+        # Generic execution errors
+        return "execution_error", f"Tool execution error: {error_str}"
+
 # Default Swagger URL
 SWAGGER_URL = "https://rootly-heroku.s3.amazonaws.com/swagger/v1/swagger.json"
 
+# Default allowed API paths
+def _generate_recommendation(solution_data: dict) -> str:
+    """Generate a high-level recommendation based on solution analysis."""
+    solutions = solution_data.get("solutions", [])
+    avg_time = solution_data.get("average_resolution_time")
+    
+    if not solutions:
+        return "No similar incidents found. This may be a novel issue requiring escalation."
+    
+    recommendation_parts = []
+    
+    # Time expectation
+    if avg_time:
+        if avg_time < 1:
+            recommendation_parts.append("Similar incidents typically resolve quickly (< 1 hour).")
+        elif avg_time > 4:
+            recommendation_parts.append("Similar incidents typically require more time (> 4 hours).")
+    
+    # Top solution
+    if solutions:
+        top_solution = solutions[0]
+        if top_solution.get("suggested_actions"):
+            actions = top_solution["suggested_actions"][:2]  # Top 2 actions
+            recommendation_parts.append(f"Consider trying: {', '.join(actions)}")
+    
+    # Pattern insights
+    patterns = solution_data.get("common_patterns", [])
+    if patterns:
+        recommendation_parts.append(f"Common patterns: {patterns[0]}")
+    
+    return " ".join(recommendation_parts) if recommendation_parts else "Review similar incidents above for resolution guidance."
+
+
 # Default allowed API paths
 DEFAULT_ALLOWED_PATHS = [
     "/incidents/{incident_id}/alerts",
@@ -230,7 +321,7 @@ def create_rootly_mcp_server(
     # By default, all routes become tools which is what we want
     mcp = FastMCP.from_openapi(
         openapi_spec=filtered_spec,
-        client=http_client,
+        client=http_client.client,
         name=name,
         timeout=30.0,
         tags={"rootly", "incident-management"},
@@ -243,42 +334,6 @@ def create_rootly_mcp_server(
         return PlainTextResponse("OK")
     
     # Add some custom tools for enhanced functionality
-    @mcp.tool()
-    async def debug_incidents() -> dict:
-        """Debug tool to inspect incidents endpoint response."""
-        try:
-            response = await make_authenticated_request("GET", "/v1/incidents", params={"page[size]": 1})
-            response.raise_for_status()
-            
-            return {
-                "status_code": response.status_code,
-                "headers": dict(response.headers),
-                "content_length": len(response.content) if response.content else 0,
-                "content_preview": response.content[:500].decode('utf-8', errors='ignore') if response.content else "No content",
-                "text_preview": response.text[:500] if hasattr(response, 'text') else "No text",
-                "encoding": response.encoding,
-                "content_type": response.headers.get('content-type', 'unknown')
-            }
-        except Exception as e:
-            return {"error": str(e), "error_type": type(e).__name__}
-
-    @mcp.tool()
-    async def debug_headers() -> dict:
-        """Debug tool to inspect request/response headers for troubleshooting."""
-        try:
-            response = await make_authenticated_request("GET", "/v1/teams", params={"page[size]": 1})
-            response.raise_for_status()
-            
-            return {
-                "request_headers": dict(response.request.headers) if response.request else {},
-                "response_headers": dict(response.headers),
-                "status_code": response.status_code,
-                "content_type": response.headers.get('content-type', 'unknown'),
-                "encoding": response.encoding,
-                "content_preview": str(response.content[:200]) if response.content else "No content"
-            }
-        except Exception as e:
-            return {"error": str(e), "error_type": type(e).__name__}
 
     @mcp.tool()
     def list_endpoints() -> list:
@@ -325,7 +380,7 @@ def create_rootly_mcp_server(
         query: Annotated[str, Field(description="Search query to filter incidents by title/summary")] = "",
         page_size: Annotated[int, Field(description="Number of results per page (max: 20)", ge=1, le=20)] = 10,
         page_number: Annotated[int, Field(description="Page number to retrieve (use 0 for all pages)", ge=0)] = 1,
-        max_results: Annotated[int, Field(description="Maximum total results when fetching all pages (ignored if page_number > 0)", ge=1, le=100)] = 20,
+        max_results: Annotated[int, Field(description="Maximum total results when fetching all pages (ignored if page_number > 0)", ge=1, le=10)] = 5,
     ) -> dict:
         """
         Search incidents with flexible pagination control.
@@ -336,7 +391,7 @@ def create_rootly_mcp_server(
         # Single page mode
         if page_number > 0:
             params = {
-                "page[size]": min(page_size, 20),
+                "page[size]": min(page_size, 5),  # Keep responses very small to avoid errors
                 "page[number]": page_number,
                 "include": "",
             }
@@ -348,15 +403,17 @@ def create_rootly_mcp_server(
                 response.raise_for_status()
                 return response.json()
             except Exception as e:
-                return {"error": str(e)}
+                error_type, error_message = MCPError.categorize_error(e)
+                return MCPError.tool_error(error_message, error_type)
 
         # Multi-page mode (page_number = 0)
         all_incidents = []
         current_page = 1
-        effective_page_size = min(page_size, 10)
+        effective_page_size = min(page_size, 5)  # Keep responses very small to avoid errors
+        max_pages = 10  # Safety limit to prevent infinite loops
 
         try:
-            while len(all_incidents) < max_results:
+            while len(all_incidents) < max_results and current_page <= max_pages:
                 params = {
                     "page[size]": effective_page_size,
                     "page[number]": current_page,
@@ -373,16 +430,23 @@ def create_rootly_mcp_server(
                     if "data" in response_data:
                         incidents = response_data["data"]
                         if not incidents:
+                            # No more incidents available
+                            break
+                        
+                        # Check if we got fewer incidents than requested (last page)
+                        if len(incidents) < effective_page_size:
+                            all_incidents.extend(incidents)
                             break
                         
                         all_incidents.extend(incidents)
 
-                        # Check if we have more pages
+                        # Check metadata if available
                         meta = response_data.get("meta", {})
                         current_page_meta = meta.get("current_page", current_page)
-                        total_pages = meta.get("total_pages", 1)
-
-                        if current_page_meta >= total_pages:
+                        total_pages = meta.get("total_pages")
+                        
+                        # If we have reliable metadata, use it
+                        if total_pages and current_page_meta >= total_pages:
                             break
 
                         current_page += 1
@@ -390,9 +454,11 @@ def create_rootly_mcp_server(
                         break
 
                 except Exception as e:
-                    # Re-raise authentication or critical errors
+                    # Re-raise authentication or critical errors for immediate handling
                     if "401" in str(e) or "Unauthorized" in str(e) or "authentication" in str(e).lower():
-                        raise e
+                        error_type, error_message = MCPError.categorize_error(e)
+                        return MCPError.tool_error(error_message, error_type)
+                    # For other errors, break loop and return partial results
                     break
 
             # Limit to max_results
@@ -410,7 +476,287 @@ def create_rootly_mcp_server(
                 }
             }
         except Exception as e:
-            return {"error": str(e)}
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(error_message, error_type)
+
+    # Initialize smart analysis tools
+    similarity_analyzer = TextSimilarityAnalyzer()
+    solution_extractor = SolutionExtractor()
+
+    @mcp.tool()
+    async def find_related_incidents(
+        incident_id: str,
+        similarity_threshold: Annotated[float, Field(description="Minimum similarity score (0.0-1.0)", ge=0.0, le=1.0)] = 0.3,
+        max_results: Annotated[int, Field(description="Maximum number of related incidents to return", ge=1, le=20)] = 5
+    ) -> dict:
+        """Find historically similar incidents to help with context and resolution strategies."""
+        try:
+            # Get the target incident details
+            target_response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+            target_response.raise_for_status()
+            target_incident_data = target_response.json()
+            target_incident = target_incident_data.get("data", {})
+            
+            if not target_incident:
+                return MCPError.tool_error("Incident not found", "not_found")
+            
+            # Get historical incidents for comparison (resolved incidents from last 6 months)
+            historical_response = await make_authenticated_request("GET", "/v1/incidents", params={
+                "page[size]": 100,  # Get more incidents for better matching
+                "page[number]": 1,
+                "filter[status]": "resolved",  # Only look at resolved incidents
+                "include": ""
+            })
+            historical_response.raise_for_status()
+            historical_data = historical_response.json()
+            historical_incidents = historical_data.get("data", [])
+            
+            # Filter out the target incident itself
+            historical_incidents = [inc for inc in historical_incidents if str(inc.get('id')) != str(incident_id)]
+            
+            if not historical_incidents:
+                return {
+                    "related_incidents": [],
+                    "message": "No historical incidents found for comparison",
+                    "target_incident": {
+                        "id": incident_id,
+                        "title": target_incident.get("attributes", {}).get("title", "")
+                    }
+                }
+            
+            # Calculate similarities
+            similar_incidents = similarity_analyzer.calculate_similarity(historical_incidents, target_incident)
+            
+            # Filter by threshold and limit results
+            filtered_incidents = [
+                inc for inc in similar_incidents 
+                if inc.similarity_score >= similarity_threshold
+            ][:max_results]
+            
+            # Format response
+            related_incidents = []
+            for incident in filtered_incidents:
+                related_incidents.append({
+                    "incident_id": incident.incident_id,
+                    "title": incident.title,
+                    "similarity_score": round(incident.similarity_score, 3),
+                    "matched_services": incident.matched_services,
+                    "matched_keywords": incident.matched_keywords,
+                    "resolution_summary": incident.resolution_summary,
+                    "resolution_time_hours": incident.resolution_time_hours
+                })
+            
+            return {
+                "target_incident": {
+                    "id": incident_id,
+                    "title": target_incident.get("attributes", {}).get("title", "")
+                },
+                "related_incidents": related_incidents,
+                "total_found": len(filtered_incidents),
+                "similarity_threshold": similarity_threshold,
+                "analysis_summary": f"Found {len(filtered_incidents)} similar incidents out of {len(historical_incidents)} historical incidents"
+            }
+            
+        except Exception as e:
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(f"Failed to find related incidents: {error_message}", error_type)
+
+    @mcp.tool()
+    async def suggest_solutions(
+        incident_id: str = "",
+        incident_title: str = "",
+        incident_description: str = "",
+        max_solutions: Annotated[int, Field(description="Maximum number of solution suggestions", ge=1, le=10)] = 3
+    ) -> dict:
+        """Suggest solutions based on similar resolved incidents. Provide either incident_id OR title/description."""
+        try:
+            target_incident = {}
+            
+            if incident_id:
+                # Get incident details by ID
+                response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+                response.raise_for_status()
+                incident_data = response.json()
+                target_incident = incident_data.get("data", {})
+                
+                if not target_incident:
+                    return MCPError.tool_error("Incident not found", "not_found")
+                    
+            elif incident_title or incident_description:
+                # Create synthetic incident for analysis
+                target_incident = {
+                    "id": "synthetic",
+                    "attributes": {
+                        "title": incident_title,
+                        "summary": incident_description,
+                        "description": incident_description
+                    }
+                }
+            else:
+                return MCPError.tool_error("Must provide either incident_id or incident_title/description", "validation_error")
+            
+            # Get resolved incidents for solution mining
+            historical_response = await make_authenticated_request("GET", "/v1/incidents", params={
+                "page[size]": 150,  # Get more incidents for better solution matching
+                "page[number]": 1,
+                "filter[status]": "resolved",
+                "include": ""
+            })
+            historical_response.raise_for_status()
+            historical_data = historical_response.json()
+            historical_incidents = historical_data.get("data", [])
+            
+            # Filter out target incident if it exists
+            if incident_id:
+                historical_incidents = [inc for inc in historical_incidents if str(inc.get('id')) != str(incident_id)]
+            
+            if not historical_incidents:
+                return {
+                    "solutions": [],
+                    "message": "No historical resolved incidents found for solution mining"
+                }
+            
+            # Find similar incidents
+            similar_incidents = similarity_analyzer.calculate_similarity(historical_incidents, target_incident)
+            
+            # Filter to reasonably similar incidents (lower threshold for solution suggestions)
+            relevant_incidents = [inc for inc in similar_incidents if inc.similarity_score >= 0.2][:max_solutions * 2]
+            
+            if not relevant_incidents:
+                return {
+                    "solutions": [],
+                    "message": "No sufficiently similar incidents found for solution suggestions",
+                    "suggestion": "This appears to be a unique incident. Consider escalating or consulting documentation."
+                }
+            
+            # Extract solutions
+            solution_data = solution_extractor.extract_solutions(relevant_incidents)
+            
+            # Format response
+            return {
+                "target_incident": {
+                    "id": incident_id or "synthetic",
+                    "title": target_incident.get("attributes", {}).get("title", incident_title),
+                    "description": target_incident.get("attributes", {}).get("summary", incident_description)
+                },
+                "solutions": solution_data["solutions"][:max_solutions],
+                "insights": {
+                    "common_patterns": solution_data["common_patterns"],
+                    "average_resolution_time_hours": solution_data["average_resolution_time"],
+                    "total_similar_incidents": solution_data["total_similar_incidents"]
+                },
+                "recommendation": _generate_recommendation(solution_data)
+            }
+            
+        except Exception as e:
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(f"Failed to suggest solutions: {error_message}", error_type)
+
+    # Add MCP resources for incidents and teams
+    @mcp.resource("incident://{incident_id}")
+    async def get_incident_resource(incident_id: str):
+        """Expose incident details as an MCP resource for easy reference and context."""
+        try:
+            response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+            response.raise_for_status()
+            incident_data = response.json()
+            
+            # Format incident data as readable text
+            incident = incident_data.get("data", {})
+            attributes = incident.get("attributes", {})
+            
+            text_content = f"""Incident #{incident_id}
+Title: {attributes.get('title', 'N/A')}
+Status: {attributes.get('status', 'N/A')}  
+Severity: {attributes.get('severity', 'N/A')}
+Created: {attributes.get('created_at', 'N/A')}
+Updated: {attributes.get('updated_at', 'N/A')}
+Summary: {attributes.get('summary', 'N/A')}
+URL: {attributes.get('url', 'N/A')}"""
+            
+            return {
+                "uri": f"incident://{incident_id}",
+                "name": f"Incident #{incident_id}",
+                "text": text_content,
+                "mimeType": "text/plain"
+            }
+        except Exception as e:
+            error_type, error_message = MCPError.categorize_error(e)
+            return {
+                "uri": f"incident://{incident_id}",
+                "name": f"Incident #{incident_id} (Error)",
+                "text": f"Error ({error_type}): {error_message}",
+                "mimeType": "text/plain"
+            }
+
+    @mcp.resource("team://{team_id}")
+    async def get_team_resource(team_id: str):
+        """Expose team details as an MCP resource for easy reference and context."""
+        try:
+            response = await make_authenticated_request("GET", f"/v1/teams/{team_id}")
+            response.raise_for_status()
+            team_data = response.json()
+            
+            # Format team data as readable text
+            team = team_data.get("data", {})
+            attributes = team.get("attributes", {})
+            
+            text_content = f"""Team #{team_id}
+Name: {attributes.get('name', 'N/A')}
+Color: {attributes.get('color', 'N/A')}
+Slug: {attributes.get('slug', 'N/A')}
+Created: {attributes.get('created_at', 'N/A')}
+Updated: {attributes.get('updated_at', 'N/A')}"""
+            
+            return {
+                "uri": f"team://{team_id}",
+                "name": f"Team: {attributes.get('name', team_id)}",
+                "text": text_content,
+                "mimeType": "text/plain"
+            }
+        except Exception as e:
+            error_type, error_message = MCPError.categorize_error(e)
+            return {
+                "uri": f"team://{team_id}",
+                "name": f"Team #{team_id} (Error)",
+                "text": f"Error ({error_type}): {error_message}",
+                "mimeType": "text/plain"
+            }
+
+    @mcp.resource("rootly://incidents")
+    async def list_incidents_resource():
+        """List recent incidents as an MCP resource for quick reference."""
+        try:
+            response = await make_authenticated_request("GET", "/v1/incidents", params={
+                "page[size]": 10,
+                "page[number]": 1,
+                "include": ""
+            })
+            response.raise_for_status()
+            data = response.json()
+            
+            incidents = data.get("data", [])
+            text_lines = ["Recent Incidents:\n"]
+            
+            for incident in incidents:
+                attrs = incident.get("attributes", {})
+                text_lines.append(f"• #{incident.get('id', 'N/A')} - {attrs.get('title', 'N/A')} [{attrs.get('status', 'N/A')}]")
+            
+            return {
+                "uri": "rootly://incidents",
+                "name": "Recent Incidents",
+                "text": "\n".join(text_lines),
+                "mimeType": "text/plain"
+            }
+        except Exception as e:
+            error_type, error_message = MCPError.categorize_error(e)
+            return {
+                "uri": "rootly://incidents", 
+                "name": "Recent Incidents (Error)",
+                "text": f"Error ({error_type}): {error_message}",
+                "mimeType": "text/plain"
+            }
+
 
     # Log server creation (tool count will be shown when tools are accessed)
     logger.info("Created Rootly MCP Server successfully")
@@ -450,18 +796,18 @@ def _load_swagger_spec(swagger_path: Optional[str] = None) -> Dict[str, Any]:
         current_dir = Path.cwd()
 
         # Check current directory first
-        swagger_path = current_dir / "swagger.json"
-        if swagger_path.is_file():
-            logger.info(f"Found Swagger file at {swagger_path}")
-            with open(swagger_path, "r", encoding="utf-8") as f:
+        local_swagger_path = current_dir / "swagger.json"
+        if local_swagger_path.is_file():
+            logger.info(f"Found Swagger file at {local_swagger_path}")
+            with open(local_swagger_path, "r", encoding="utf-8") as f:
                 return json.load(f)
 
         # Check parent directories
         for parent in current_dir.parents:
-            swagger_path = parent / "swagger.json"
-            if swagger_path.is_file():
-                logger.info(f"Found Swagger file at {swagger_path}")
-                with open(swagger_path, "r", encoding="utf-8") as f:
+            parent_swagger_path = parent / "swagger.json"
+            if parent_swagger_path.is_file():
+                logger.info(f"Found Swagger file at {parent_swagger_path}")
+                with open(parent_swagger_path, "r", encoding="utf-8") as f:
                     return json.load(f)
 
         # If the file wasn't found, fetch it from the URL and save it
@@ -469,12 +815,12 @@ def _load_swagger_spec(swagger_path: Optional[str] = None) -> Dict[str, Any]:
         swagger_spec = _fetch_swagger_from_url()
 
         # Save the fetched spec to the current directory
-        swagger_path = current_dir / "swagger.json"
-        logger.info(f"Saving Swagger file to {swagger_path}")
+        save_swagger_path = current_dir / "swagger.json"
+        logger.info(f"Saving Swagger file to {save_swagger_path}")
         try:
-            with open(swagger_path, "w", encoding="utf-8") as f:
+            with open(save_swagger_path, "w", encoding="utf-8") as f:
                 json.dump(swagger_spec, f)
-            logger.info(f"Saved Swagger file to {swagger_path}")
+            logger.info(f"Saved Swagger file to {save_swagger_path}")
         except Exception as e:
             logger.warning(f"Failed to save Swagger file: {e}")