rootly-mcp-server 2.3.3__tar.gz → 2.3.7__tar.gz

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/.gitignore

@@ -199,4 +199,3 @@ test_output/
 !CONTRIBUTING.md
 !CHANGELOG.md
 .beads/
-.mcp.json

rootly_mcp_server-2.3.7/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "rootly": {
+      "url": "https://mcp.rootly.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${ROOTLY_API_TOKEN}"
+      }
+    }
+  }
+}

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/CHANGELOG.md

@@ -5,59 +5,93 @@ All notable changes to the Rootly MCP Server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.3.2] - Released 2026-04-23
+## [2.3.7] - Released 2026-05-08
+
+### Features
+
+- **MCP OAuth2 Authorization Discovery**: Added hosted-only OAuth protected resource metadata and `WWW-Authenticate` discovery headers so compatible MCP clients can discover Rootly's authorization server automatically
 
 ### Fixed
 
-- **Generated Write Payload Forwarding**: Normalized generated OpenAPI write-tool payloads to unwrap top-level `body` envelopes before forwarding to the Rootly API, fixing failures such as `createWorkflow` returning `Invalid payload ({data: "Expected hash"})`
+- **Hosted Streamable HTTP Session Accumulation**: Defaulted hosted streamable HTTP to stateless mode so the server no longer accumulates long-lived MCP sessions when clients do not explicitly terminate them
+- **Full Hosted HTTP Coverage**: Applied the stateless hosted default to both dual-transport deployments and direct hosted `streamable-http` mode for consistent leak mitigation
+
+### Configuration
+
+- **Hosted Docker Default**: Set `FASTMCP_STATELESS_HTTP=true` in the Docker image so standard hosted deployments use the safer stateless configuration by default while still allowing explicit operator override
 
 ### Testing
 
-- **Request-Path Regression Coverage**: Added transport regression tests that assert write requests forward unwrapped JSON payloads and preserve already-correct non-envelope payloads
+- **Hosted Transport Coverage**: Added focused tests for hosted stateless defaults and explicit `FASTMCP_STATELESS_HTTP` override behavior across both transport entry paths
 
-## [2.3.1] - Released 2026-04-23
+## [2.3.6] - Released 2026-05-07
+
+### Features
+
+- **Open Plugins Discovery Support**: Added a root `.mcp.json` so plugin catalogs like cursor.directory can auto-detect the hosted Rootly MCP configuration and generate one-click install flows
+
+### Dependencies
+
+- **Routine Dependency Refresh**: Pulled in the latest minor and patch dependency updates from Dependabot
+
+## [2.3.5] - Released 2026-05-07
 
 ### Fixed
 
-- **Create Operations Restored**: Restored missing create operations for workflows, schedules, and configuration resources by expanding `DEFAULT_WRITE_ALLOWED_PATHS` to include collection/base paths (not only `/{id}` update paths)
-- **Write Surface Completeness**: Re-enabled create + update parity across key families including workflows, workflow groups, schedules, escalation policies, services, teams, environments, dashboards, playbooks, monitoring, retrospectives, communications, causes, and catalogs
-- **Test Accuracy**: Corrected alert source tool-name assertions in unit tests (`createAlertSource` / `updateAlertSource`) to prevent false confidence
+- **Sequential Incident Reference Resolution**: Added server-side resolution for incident references like `4460`, `#4460`, and `INC-4460`, so callers no longer need to convert sequential incident numbers to UUIDs themselves
+- **Broader Incident Tool Support**: Applied the same reference resolution behavior across `getIncident`, `updateIncident`, `find_related_incidents`, `suggest_solutions`, and the `incident://{incident_id}` resource for a more consistent incident workflow
 
-### Notes
+### Testing
 
-- `createWorkflow` remains the correct tool name (singular), not `createWorkflows`
-- Security exclusions for sensitive families remain unchanged
+- **Incident Reference Coverage**: Added focused test coverage for UUID and sequential incident references, not-found handling, bounded lookup behavior, and the expanded incident tool/resource paths
 
-## [2.3.0] - Released 2026-04-23
+## [2.3.4] - Released 2026-04-30
 
 ### Features
 
-- **Comprehensive API Coverage Expansion**: Expanded MCP tool surface from 124 to 150+ tools by updating to latest Rootly API specification with 95+ operations
-- **Enhanced Tool Discoverability**: Added contextual "WHEN TO USE" guidance to tool descriptions for improved AI agent decision-making
-- **Workflow-Focused Tool Subsets**: Introduced 5 predefined tool configurations optimized for specific use cases (Incident Response, Schedule Management, Monitoring Setup, Retrospectives, Administration)
-- **Operational Context Resources**: Added new MCP resources for real-time operational awareness:
-  - `rootly://oncall-status` - Live on-call status across teams for incident response context
-  - `rootly://workflow-guide` - Step-by-step workflow guidance for common Rootly operations
-- **Expanded Write Operations**: Added 54 non-destructive write operations while maintaining security boundaries
-- **API Path Coverage**: Increased DEFAULT_ALLOWED_PATHS from ~80 to 151 endpoints covering workflows, dashboards, communications, playbooks, and monitoring
+- **Incident Timeline Events Enabled by Default**: Enabled creating incident timeline events by default, so timeline entries can now be created through MCP without extra configuration
 
-### Enhanced
+### Dependencies
 
-- **Tool Descriptions**: Enhanced incident and on-call tool descriptions with specific usage context and best practices
-- **Environment Configuration**: Improved environment-based tool subset configuration following MCP best practices
-- **Error Handling**: Robust error handling in new resource implementations with proper categorization
+- **Routine Dependency Refresh**: Pulled in the latest minor and patch dependency updates from Dependabot
 
-### Documentation
+## [2.3.3] - Released 2026-04-23
 
-- **README Updates**: Updated tool counts, added workflow subset configurations, and enhanced setup guidance
-- **Configuration Examples**: Added 5 workflow-focused environment configurations for optimal AI performance
-- **API Coverage**: Documented comprehensive endpoint coverage while highlighting security exclusions
+### Fixed
 
-### Security
+- **Schema and Path Interpretation**: Improved how the MCP interprets API schemas and path patterns so more tools can be exposed correctly
+- **Write Path Coverage**: Fixed write-path coverage gaps so generated tools line up more reliably with endpoints that support write actions
+- **Write Availability Guidance**: Improved the guidance returned when a write action is not available for the current endpoint or configuration
+- **Hyphenated Resource Matching**: Tightened path matching so hyphenated resources like `status-pages` are handled correctly
+
+## [2.3.2] - Released 2026-04-23
+
+### Fixed
+
+- **Generated Write Request Shape**: Fixed how generated MCP tools send create and update requests for API-backed endpoints
+- **Affected Endpoints**: This affected tools tied to endpoints like `/v1/workflows`, `/v1/workflow_groups`, `/v1/schedules`, and other generated write operations that expected a specific request shape
+- **Create Workflow Reliability**: As a result, tools like `createWorkflow` can complete successfully instead of stopping during request submission
+
+### Testing
+
+- **Request-Path Regression Coverage**: Added transport regression tests that assert write requests forward unwrapped JSON payloads and preserve already-correct non-envelope payloads
+
+## [2.3.1] - Released 2026-04-23
+
+### Fixed
+
+- **Restored Create Actions**: Restored missing create actions for key configuration endpoints, including workflows, workflow groups, schedules, schedule rotations, escalation policies, escalation paths, services, teams, and environments
+- **Create and Update Parity**: Closed the gap where users could list or update those records but could not create new ones through MCP
+- **Test Accuracy**: Corrected alert source tool-name assertions in unit tests (`createAlertSource` / `updateAlertSource`)
+
+## [2.3.0] - Released 2026-04-23
+
+### Features
 
-- **Maintained Boundaries**: Preserved security exclusions for sensitive operations (API keys, user management, webhooks, financial data)
-- **Curated Approach**: Continued read-first philosophy with carefully selected write operations
-- **Input Validation**: Maintained existing security controls and validation patterns
+- **Broader API Coverage**: Expanded the MCP to cover many more Rootly API areas, including workflows, workflow groups, workflow tasks, schedules, schedule rotations, escalation policies, escalation paths, services, teams, environments, dashboards, playbooks, retrospectives, and monitoring-related resources
+- **More Write Actions**: Added more write actions across those areas, especially update actions, so the MCP can do more than just read data
+- **Wider Operational Use**: Made the MCP useful for more operational and configuration work, not just incident search and on-call lookups
+- **Workflow-Focused Tooling**: Introduced workflow-focused tool subsets and supporting resources for common MCP use cases
 
 ### Testing
 

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/Dockerfile

@@ -28,6 +28,7 @@ EXPOSE 8000
 ENV PYTHONUNBUFFERED=1
 ENV FASTMCP_HOST=0.0.0.0
 ENV FASTMCP_PORT=8000
+ENV FASTMCP_STATELESS_HTTP=true
 ENV ROOTLY_TRANSPORT=both
 ENV ROOTLY_LOG_LEVEL=INFO
 

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rootly-mcp-server
-Version: 2.3.3
+Version: 2.3.7
 Summary: Secure Model Context Protocol server for Rootly APIs with AI SRE capabilities, comprehensive error handling, and input validation
 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
@@ -24,10 +24,10 @@ Requires-Python: >=3.12
 Requires-Dist: authlib>=1.6.11
 Requires-Dist: brotli>=1.2.0
 Requires-Dist: cryptography>=46.0.7
-Requires-Dist: fastmcp[code-mode]==3.2.0
+Requires-Dist: fastmcp[code-mode]==3.2.4
 Requires-Dist: httpx==0.28.1
 Requires-Dist: numpy>=1.24.0
-Requires-Dist: pydantic==2.12.5
+Requires-Dist: pydantic==2.13.3
 Requires-Dist: pygments>=2.20.0
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: python-multipart>=0.0.26

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rootly-mcp-server"
-version = "2.3.3"
+version = "2.3.7"
 description = "Secure Model Context Protocol server for Rootly APIs with AI SRE capabilities, comprehensive error handling, and input validation"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -36,7 +36,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dependencies = [
-    "fastmcp[code-mode]==3.2.0",  # Pin to patched version with Code Mode support
+    "fastmcp[code-mode]==3.2.4",  # Pin to patched version with Code Mode support
     "authlib>=1.6.11",  # Override vulnerable transitive authlib (GHSA-jj8c-mmj3-mmgv)
     "python-dotenv>=1.2.2",  # Override vulnerable transitive python-dotenv (GHSA-m8f7-34r5-grfg)
     "python-multipart>=0.0.26",  # Override vulnerable transitive python-multipart (CVE-2026-40347)
@@ -44,7 +44,7 @@ dependencies = [
     "Pygments>=2.20.0",  # Override vulnerable transitive Pygments
     "requests==2.33.1", # Pin to patched version
     "httpx==0.28.1",   # Pin to specific version
-    "pydantic==2.12.5",  # Pin to specific version
+    "pydantic==2.13.3",  # Pin to specific version
     "brotli>=1.2.0",    # For Brotli compression support in httpx
     "scikit-learn>=1.3.0", # For text similarity and ML utilities
     "numpy>=1.24.0",    # For numerical operations

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/src/rootly_mcp_server/__main__.py

@@ -63,6 +63,20 @@ def normalize_transport_or_default(value: str, default: TransportName = "stdio")
         return default
 
 
+def streamable_http_stateless_enabled(*, hosted: bool, fastmcp_stateless_http: bool) -> bool:
+    """Choose streamable HTTP session mode with a safe hosted default.
+
+    Hosted streamable HTTP traffic is high-churn and most clients do not send
+    DELETE to close MCP sessions. On current MCP SDK versions that leaks
+    stateful session transports until process restart. We therefore default
+    hosted deployments to stateless mode unless the operator explicitly sets
+    ``FASTMCP_STATELESS_HTTP``.
+    """
+    if "FASTMCP_STATELESS_HTTP" in os.environ:
+        return fastmcp_stateless_http
+    return hosted
+
+
 def parse_args():
     """Parse command-line arguments."""
     parser = argparse.ArgumentParser(description="Start the Rootly MCP server for API integration.")
@@ -259,7 +273,12 @@ def run_dual_http_server(
     sse_path = fastmcp.settings.sse_path
     streamable_path = fastmcp.settings.streamable_http_path
     message_path = fastmcp.settings.message_path
-    stateless_http = fastmcp.settings.stateless_http
+    stateless_http = streamable_http_stateless_enabled(
+        hosted=True, fastmcp_stateless_http=fastmcp.settings.stateless_http
+    )
+    logger.info(
+        "Streamable HTTP configured in %s mode", "stateless" if stateless_http else "stateful"
+    )
 
     sse_transport = SseServerTransport(message_path)
 
@@ -453,6 +472,11 @@ def main():
                 logger.info("Code Mode enabled at path: %s", code_mode_path)
 
         logger.info(f"Running server with transport: {normalized_transport}...")
+        direct_streamable_stateless_http = streamable_http_stateless_enabled(
+            hosted=hosted_mode,
+            fastmcp_stateless_http=os.getenv("FASTMCP_STATELESS_HTTP", "").lower()
+            in ("true", "1", "yes"),
+        )
         if normalized_transport == "both":
             run_dual_http_server(
                 server=server,
@@ -464,13 +488,16 @@ def main():
         elif normalized_transport == "stdio":
             server.run(transport=normalized_transport)
         else:
-            server.run(
-                transport=normalized_transport,
-                middleware=get_hosted_auth_middleware(),
+            run_kwargs = {
+                "transport": normalized_transport,
+                "middleware": get_hosted_auth_middleware(),
                 # Override FastMCP's default of 0s to allow active SSE connections
                 # to finish gracefully during deployments (avoids 502s).
-                uvicorn_config={"timeout_graceful_shutdown": 30},
-            )
+                "uvicorn_config": {"timeout_graceful_shutdown": 30},
+            }
+            if normalized_transport == "streamable-http":
+                run_kwargs["stateless_http"] = direct_streamable_stateless_http
+            server.run(**run_kwargs)
 
     except FileNotFoundError as e:
         logger.error(f"File not found: {e}")

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/src/rootly_mcp_server/server.py

@@ -25,7 +25,12 @@ from .tools.alerts import register_alert_tools
 from .tools.incidents import register_incident_tools
 from .tools.oncall import register_oncall_tools
 from .tools.resources import register_resource_handlers
-from .utils import sanitize_parameters_in_spec
+from .utils import (
+    OAUTH_PROTECTED_RESOURCE_PATH,
+    is_mcp_server_url_static,
+    resolve_mcp_server_url,
+    sanitize_parameters_in_spec,
+)
 
 # Set up logger
 logger = logging.getLogger(__name__)
@@ -541,6 +546,40 @@ def create_rootly_mcp_server(
 
         return PlainTextResponse("OK")
 
+    # OAuth 2.0 Protected Resource Metadata (RFC 9728)
+    # MCP clients fetch this to discover which authorization server to use.
+    if hosted:
+        from starlette.responses import JSONResponse
+
+        async def _oauth_protected_resource_handler(request):
+            mcp_server_url = resolve_mcp_server_url(request)
+
+            cache = "max-age=3600" if is_mcp_server_url_static() else "no-store"
+            return JSONResponse(
+                {
+                    "resource": mcp_server_url,
+                    "authorization_servers": [base_url],
+                    "scopes_supported": [
+                        "openid",
+                        "profile",
+                        "email",
+                        "all",
+                    ],
+                    "bearer_methods_supported": ["header"],
+                },
+                headers={"Cache-Control": cache},
+            )
+
+        # RFC 9728 §5: clients may request the path-suffixed variant first
+        # (e.g. /.well-known/oauth-protected-resource/mcp for a resource at /mcp).
+        @mcp.custom_route(OAUTH_PROTECTED_RESOURCE_PATH + "/{path:path}", methods=["GET"])
+        async def oauth_protected_resource_suffixed(request):
+            return await _oauth_protected_resource_handler(request)
+
+        @mcp.custom_route(OAUTH_PROTECTED_RESOURCE_PATH, methods=["GET"])
+        async def oauth_protected_resource(request):
+            return await _oauth_protected_resource_handler(request)
+
     # Add some custom tools for enhanced functionality
 
     @mcp.tool()

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/src/rootly_mcp_server/server_defaults.py

@@ -349,6 +349,7 @@ DEFAULT_WRITE_ALLOWED_PATHS = [
     # Incident mutations
     "/alert_events/{id}",
     "/incidents/{incident_id}/action_items",
+    "/incidents/{incident_id}/events",
     "/incidents/{incident_id}/form_field_selections",
     "/incident_form_field_selections/{id}",
     # On-call schedules - create + update

{rootly_mcp_server-2.3.3 → rootly_mcp_server-2.3.7}/src/rootly_mcp_server/tools/incidents.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from collections.abc import Awaitable, Callable
 from typing import Annotated, Any, Literal, cast
 
@@ -22,6 +23,12 @@ INCIDENT_LIST_FIELDS = (
     "id,sequential_id,title,summary,status,severity,created_at,updated_at,url,"
     "started_at,resolved_at,retrospective_progress_status"
 )
+INCIDENT_REFERENCE_FIELDS = "id,sequential_id"
+INCIDENT_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+INCIDENT_SEQUENTIAL_REF_RE = re.compile(r"^(?:#|INC-)?(\d+)$")
 
 
 def _split_csv_values(value: str) -> list[str]:
@@ -76,6 +83,110 @@ def _summarize_incident_record(incident: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _extract_sequential_id(incident: dict[str, Any]) -> int | None:
+    """Extract a numeric sequential incident ID from a Rootly incident record."""
+    attrs = incident.get("attributes", {})
+    sequential_id = attrs.get("sequential_id")
+    if sequential_id is None:
+        return None
+    try:
+        return int(sequential_id)
+    except (TypeError, ValueError):
+        return None
+
+
+def _normalize_incident_reference(reference: str) -> tuple[str, str | int]:
+    """Classify and normalize an incident reference."""
+    normalized = _normalize_optional_text(reference)
+    if normalized is None:
+        raise ValueError("Incident reference is required")
+    if INCIDENT_UUID_RE.match(normalized):
+        return ("uuid", normalized)
+    sequential_match = INCIDENT_SEQUENTIAL_REF_RE.match(normalized)
+    if sequential_match:
+        return ("sequential", int(sequential_match.group(1)))
+    return ("direct", normalized)
+
+
+async def _resolve_incident_reference_to_uuid(
+    incident_reference: str,
+    make_authenticated_request: MakeAuthenticatedRequest,
+) -> str:
+    """Resolve supported incident references to the Rootly incident UUID."""
+    reference_kind, normalized_reference = _normalize_incident_reference(incident_reference)
+    if reference_kind in {"uuid", "direct"}:
+        return cast(str, normalized_reference)
+
+    target_sequential_id = cast(int, normalized_reference)
+    page_cache: dict[int, tuple[list[dict[str, Any]], dict[str, Any]]] = {}
+
+    async def _fetch_page(page_number: int) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        cached = page_cache.get(page_number)
+        if cached is not None:
+            return cached
+
+        response = await make_authenticated_request(
+            "GET",
+            "/v1/incidents",
+            params={
+                "page[size]": 100,
+                "page[number]": page_number,
+                "fields[incidents]": INCIDENT_REFERENCE_FIELDS,
+                "include": "",
+                "sort": "-created_at",
+            },
+        )
+        response.raise_for_status()
+        response_data = response.json()
+        incidents = cast(list[dict[str, Any]], response_data.get("data", []))
+        meta = cast(dict[str, Any], response_data.get("meta", {}))
+        page_cache[page_number] = (incidents, meta)
+        return incidents, meta
+
+    incidents, meta = await _fetch_page(1)
+    total_pages = int(meta.get("total_pages") or 1)
+
+    left = 1
+    right = total_pages
+
+    while left <= right:
+        page_number = (left + right) // 2
+        if page_number == 1:
+            page_incidents, _ = incidents, meta
+        else:
+            page_incidents, _ = await _fetch_page(page_number)
+
+        sequential_ids = [
+            sequential_id
+            for sequential_id in (_extract_sequential_id(incident) for incident in page_incidents)
+            if sequential_id is not None
+        ]
+
+        if not sequential_ids:
+            break
+
+        page_max = max(sequential_ids)
+        page_min = min(sequential_ids)
+
+        if target_sequential_id > page_max:
+            right = page_number - 1
+            continue
+        if target_sequential_id < page_min:
+            left = page_number + 1
+            continue
+
+        for incident in page_incidents:
+            if _extract_sequential_id(incident) == target_sequential_id:
+                incident_uuid = incident.get("id")
+                if isinstance(incident_uuid, str) and incident_uuid:
+                    return incident_uuid
+                break
+
+        raise LookupError(f"Incident reference not found: INC-{target_sequential_id}")
+
+    raise LookupError(f"Incident reference not found: INC-{target_sequential_id}")
+
+
 def register_incident_tools(
     mcp: Any,
     make_authenticated_request: MakeAuthenticatedRequest,
@@ -624,11 +735,21 @@ def register_incident_tools(
 
     @mcp.tool(name="getIncident")
     async def get_incident(
-        incident_id: Annotated[str, Field(description="Incident ID to retrieve")],
+        incident_id: Annotated[
+            str,
+            Field(
+                description="Incident reference to retrieve: UUID, bare number like 4460, #4460, or INC-4460"
+            ),
+        ],
     ) -> JsonDict:
         """Retrieve a single incident with PIR-related fields for direct verification."""
         try:
-            response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+            resolved_incident_id = await _resolve_incident_reference_to_uuid(
+                incident_id, make_authenticated_request
+            )
+            response = await make_authenticated_request(
+                "GET", f"/v1/incidents/{resolved_incident_id}"
+            )
             response.raise_for_status()
 
             response_data = response.json()
@@ -636,6 +757,22 @@ def register_incident_tools(
                 stripped = strip_heavy_nested_data({"data": [response_data["data"]]})
                 response_data["data"] = stripped["data"][0]
             return cast(JsonDict, response_data)
+        except ValueError as e:
+            return cast(
+                JsonDict,
+                mcp_error.tool_error(
+                    f"Failed to retrieve incident: {e}",
+                    "validation_error",
+                ),
+            )
+        except LookupError as e:
+            return cast(
+                JsonDict,
+                mcp_error.tool_error(
+                    f"Failed to retrieve incident: {e}",
+                    "not_found",
+                ),
+            )
         except Exception as e:
             error_type, error_message = mcp_error.categorize_error(e)
             return cast(
@@ -744,7 +881,12 @@ def register_incident_tools(
 
         @mcp.tool(name="updateIncident")
         async def update_incident(
-            incident_id: Annotated[str, Field(description="Incident ID to update")],
+            incident_id: Annotated[
+                str,
+                Field(
+                    description="Incident reference to update: UUID, bare number like 4460, #4460, or INC-4460"
+                ),
+            ],
             retrospective_progress_status: Annotated[
                 str | None,
                 Field(
@@ -791,8 +933,11 @@ def register_incident_tools(
             }
 
             try:
+                resolved_incident_id = await _resolve_incident_reference_to_uuid(
+                    incident_id, make_authenticated_request
+                )
                 response = await make_authenticated_request(
-                    "PUT", f"/v1/incidents/{incident_id}", json=payload
+                    "PUT", f"/v1/incidents/{resolved_incident_id}", json=payload
                 )
                 response.raise_for_status()
 
@@ -842,11 +987,15 @@ def register_incident_tools(
         """
         try:
             target_incident: dict[str, Any] = {}
+            resolved_incident_id = ""
 
             if incident_id:
                 # Get the target incident details by ID
+                resolved_incident_id = await _resolve_incident_reference_to_uuid(
+                    incident_id, make_authenticated_request
+                )
                 target_response = await make_authenticated_request(
-                    "GET", f"/v1/incidents/{incident_id}"
+                    "GET", f"/v1/incidents/{resolved_incident_id}"
                 )
                 target_response.raise_for_status()
                 target_incident_data = strip_heavy_nested_data(
@@ -898,7 +1047,9 @@ def register_incident_tools(
             # Filter out the target incident itself if it exists
             if incident_id:
                 historical_incidents = [
-                    inc for inc in historical_incidents if str(inc.get("id")) != str(incident_id)
+                    inc
+                    for inc in historical_incidents
+                    if str(inc.get("id")) != str(resolved_incident_id)
                 ]
 
             if not historical_incidents:
@@ -907,6 +1058,7 @@ def register_incident_tools(
                     "message": "No historical incidents found for comparison",
                     "target_incident": {
                         "id": incident_id or "synthetic",
+                        "resolved_incident_id": resolved_incident_id or None,
                         "title": target_incident.get("attributes", {}).get(
                             "title", incident_description
                         ),
@@ -941,6 +1093,7 @@ def register_incident_tools(
             return {
                 "target_incident": {
                     "id": incident_id or "synthetic",
+                    "resolved_incident_id": resolved_incident_id or None,
                     "title": target_incident.get("attributes", {}).get(
                         "title", incident_description
                     ),
@@ -988,10 +1141,16 @@ def register_incident_tools(
         """
         try:
             target_incident: dict[str, Any] = {}
+            resolved_incident_id = ""
 
             if incident_id:
                 # Get incident details by ID
-                response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+                resolved_incident_id = await _resolve_incident_reference_to_uuid(
+                    incident_id, make_authenticated_request
+                )
+                response = await make_authenticated_request(
+                    "GET", f"/v1/incidents/{resolved_incident_id}"
+                )
                 response.raise_for_status()
                 incident_data = strip_heavy_nested_data({"data": [response.json().get("data", {})]})
                 target_incident = incident_data.get("data", [{}])[0]
@@ -1039,7 +1198,9 @@ def register_incident_tools(
             # 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)
+                    inc
+                    for inc in historical_incidents
+                    if str(inc.get("id")) != str(resolved_incident_id)
                 ]
 
             if not historical_incidents:
@@ -1073,6 +1234,7 @@ def register_incident_tools(
             return {
                 "target_incident": {
                     "id": incident_id or "synthetic",
+                    "resolved_incident_id": resolved_incident_id or None,
                     "title": target_incident.get("attributes", {}).get("title", incident_title),
                     "description": target_incident.get("attributes", {}).get(
                         "summary", incident_description