Rootly-AI-Labs/Rootly-MCP-server

Dynamically parses Rootly's OpenAPI/Swagger specification and generates MCP-compatible tools without manual tool definition. Uses FastMCP.from_openapi() to introspect the OpenAPI schema, extract endpoint metadata (paths, methods, parameters, request/response schemas), and automatically create callable tools with proper input validation and type coercion. The server initialization pipeline (create_rootly_mcp_server() in server.py) orchestrates this transformation, mapping REST endpoints to MCP tool signatures with parameter sanitization and schema-based validation.

Implements ML-based incident correlation using TF-IDF (Term Frequency-Inverse Document Frequency) vectorization to find semantically similar incidents across the Rootly platform. The smart_utils.py module (TextSimilarityAnalyze tool) tokenizes incident titles, descriptions, and metadata, builds a TF-IDF matrix, and computes cosine similarity scores to rank incidents by relevance. This enables AI agents to automatically detect duplicate or related incidents without explicit keyword matching, improving incident deduplication and root cause analysis by connecting incidents with similar symptoms or error patterns.

Provides a testing infrastructure (tests/unit/test_oncall_handoff.py and related fixtures) for validating MCP server functionality, including unit tests for individual tools, integration tests for API interactions, and test fixtures for mocking Rootly API responses. The framework includes utilities for creating test incidents, on-call schedules, and API responses, enabling developers to write tests without hitting the live Rootly API. Tests validate tool parameter validation, error handling, and correct API request formatting.

Implements a GitHub Actions-based CI/CD pipeline (documented in Deployment & Operations) that automatically tests, builds, and deploys the MCP server to AWS infrastructure. The pipeline runs on every commit, executing unit tests, linting, and type checking before building a Docker container and pushing it to AWS ECR. Semaphore CI integration enables additional deployment stages for staging and production environments. The pipeline ensures code quality and enables rapid iteration while maintaining reliability.

Analyzes incident resolution history to extract and recommend solutions for new incidents using pattern matching and text analysis. The smart_utils.py module includes solution extraction logic that parses incident timelines, resolution notes, and remediation steps to identify common resolution patterns. When a new incident is created, the system searches historical incidents for similar problems and surfaces the solutions that were applied, enabling AI agents to suggest resolution steps based on past successful resolutions without requiring manual runbook lookup.

Provides intelligent on-call management through tools that query on-call schedules, compute handoff timing, and recommend escalation paths based on current on-call assignments. The on-call intelligence tools (referenced in test_oncall_handoff.py) integrate with Rootly's on-call API endpoints to fetch current schedules, identify who is on-call for specific services, and calculate handoff windows. The system uses the on-call data to help AI agents make context-aware decisions about incident assignment, escalation, and notification routing without requiring manual schedule lookups.

Provides a custom AuthenticatedHTTPXClient (server.py 175-276) that automatically injects Rootly API credentials into all outbound requests and transforms tool parameters into valid REST API calls. The client intercepts tool invocations, reads the ROOTLY_API_TOKEN from environment, adds Authorization headers, and converts MCP tool parameters (which may use different naming conventions) into the format expected by Rootly's REST API. This abstraction eliminates the need for individual tools to handle authentication or parameter mapping, centralizing credential management and API contract translation.

Implements full Model Context Protocol (MCP) compliance using FastMCP framework with Server-Sent Events (SSE) as the transport mechanism. The server (src/rootly_mcp_server/server.py) initializes a FastMCP instance that handles MCP protocol details including tool registration, resource exposure, and request/response serialization. The SSE transport (used in production at https://mcp.rootly.com/sse) enables bidirectional communication between MCP clients (Cursor, Windsurf, Claude Desktop) and the Rootly server without requiring WebSocket or long-polling, using HTTP streaming for efficiency.

Implements parameter sanitization and validation using OpenAPI schema definitions to ensure tool inputs conform to API requirements before execution. The server validates parameters against the OpenAPI schema during tool invocation, rejecting invalid inputs with descriptive error messages. This includes type checking (e.g., integer vs string), required field validation, enum constraint enforcement, and string length/pattern validation. The sanitization layer (referenced in Advanced Topics) prevents malformed requests from reaching the Rootly API, reducing error rates and improving reliability.

Exposes Rootly incident data and documentation as MCP resources, enabling AI agents to read incident details, timelines, and related documentation without invoking tools. Resources are read-only data endpoints that return structured incident information (JSON) or documentation (markdown/text). The server registers resources for common incident queries (e.g., 'get incident by ID', 'list recent incidents') and documentation (e.g., 'Rootly API reference', 'incident response runbooks'), allowing AI agents to fetch context without tool invocation overhead.

Implements a robust server startup pipeline (src/rootly_mcp_server/__main__.py) that validates environment configuration, loads API credentials, initializes the FastMCP server, and registers all tools before accepting client connections. The pipeline checks for required environment variables (ROOTLY_API_TOKEN), validates API connectivity, loads the OpenAPI specification, and generates tools dynamically. If any validation step fails, the server exits with a descriptive error message, preventing misconfigured deployments from running.

Provides a framework for developing custom tools beyond auto-generated OpenAPI tools, enabling teams to add domain-specific logic (incident analysis, solution mining, on-call intelligence) as MCP tools. The framework (documented in Development Guide) allows developers to define custom tools using Python functions decorated with FastMCP tool decorators, with automatic parameter validation and error handling. Custom tools can access the Rootly API through the AuthenticatedHTTPXClient, leverage smart analysis utilities (TF-IDF, solution extraction), and integrate seamlessly with auto-generated tools in the same MCP interface.