devhelm-mcp-server 0.7.0__tar.gz → 0.8.2__tar.gz

{devhelm_mcp_server-0.7.0 → devhelm_mcp_server-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devhelm-mcp-server
-Version: 0.7.0
+Version: 0.8.2
 Summary: DevHelm MCP server — AI agent access to monitors, incidents, alerting, and more
 Project-URL: Homepage, https://devhelm.io
 Project-URL: Repository, https://github.com/devhelmhq/mcp-server
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
-Requires-Dist: devhelm>=0.6.0
+Requires-Dist: devhelm>=0.7.2
 Requires-Dist: fastmcp>=2.0.0
 Description-Content-Type: text/markdown
 

{devhelm_mcp_server-0.7.0 → devhelm_mcp_server-0.8.2}/docs/openapi/monitoring-api.json

@@ -166,8 +166,52 @@
           "Alert Channels"
         ],
         "summary": "List active alert channels for the authenticated org",
+        "description": "Supports filtering by `type` (channel integration), `managedBy` (creating surface), and `search` (case-insensitive contains on name). Unrecognised query parameters are silently ignored — pin to the documented set above.",
         "operationId": "list_14",
         "parameters": [
+          {
+            "name": "type",
+            "in": "query",
+            "description": "Filter by channel integration type (e.g. SLACK, WEBHOOK, EMAIL)",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "email",
+                "webhook",
+                "slack",
+                "pagerduty",
+                "opsgenie",
+                "teams",
+                "discord"
+              ]
+            }
+          },
+          {
+            "name": "managedBy",
+            "in": "query",
+            "description": "Filter by managed-by source (DASHBOARD, CLI, TERRAFORM, MCP, API)",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "DASHBOARD",
+                "CLI",
+                "TERRAFORM",
+                "MCP",
+                "API"
+              ]
+            }
+          },
+          {
+            "name": "search",
+            "in": "query",
+            "description": "Case-insensitive contains-match on the channel name",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "pageable",
             "in": "query",
@@ -6374,17 +6418,27 @@
           "Monitors"
         ],
         "summary": "List monitors for the authenticated org",
+        "description": "Supports filtering by `enabled`, `status` (alias active|paused for enabled), `type`, `managedBy`, `tag` / `tags`, `search`, and `environmentId`. Unrecognised query parameters are silently ignored (Spring's default binding behaviour) — pin to the documented set above.",
         "operationId": "list_8",
         "parameters": [
           {
             "name": "enabled",
             "in": "query",
-            "description": "Filter by enabled state",
+            "description": "Filter by enabled state (true/false)",
             "required": false,
             "schema": {
               "type": "boolean"
             }
           },
+          {
+            "name": "status",
+            "in": "query",
+            "description": "Lifecycle status alias: 'active' (enabled=true) or 'paused' (enabled=false). Ignored when ?enabled is also supplied.",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "type",
             "in": "query",
@@ -6412,14 +6466,25 @@
               "enum": [
                 "DASHBOARD",
                 "CLI",
-                "TERRAFORM"
+                "TERRAFORM",
+                "MCP",
+                "API"
               ]
             }
           },
           {
             "name": "tags",
             "in": "query",
-            "description": "Filter by tag names, comma-separated (e.g. prod,critical)",
+            "description": "Filter by tag names, comma-separated (e.g. prod,critical); OR semantics",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tag",
+            "in": "query",
+            "description": "Filter by a single tag name (alias for ?tags=); merged with ?tags using OR semantics",
             "required": false,
             "schema": {
               "type": "string"
@@ -21727,6 +21792,18 @@
             "description": "SHA-256 hash of the channel config; use for change detection",
             "nullable": true
           },
+          "managedBy": {
+            "type": "string",
+            "description": "Source that created/owns this channel: DASHBOARD, CLI, TERRAFORM, MCP, or API. Null on channels created before this attribution column existed.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
+          },
           "lastDeliveryAt": {
             "type": "string",
             "description": "Timestamp of the most recent delivery attempt",
@@ -22927,6 +23004,18 @@
                 "$ref": "#/components/schemas/WebhookChannelConfig"
               }
             ]
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "Source creating this channel: DASHBOARD, CLI, TERRAFORM, MCP, or API. Defaults to API when omitted.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         }
       },
@@ -23187,12 +23276,14 @@
             "maxLength": 100,
             "minLength": 0,
             "type": "string",
-            "description": "iCal RRULE for recurring windows (max 100 chars); null for one-time",
+            "description": "Reserved: iCal RRULE for recurring windows (stored but not yet honored)",
             "nullable": true
           },
           "reason": {
+            "maxLength": 500,
+            "minLength": 0,
             "type": "string",
-            "description": "Human-readable reason for the maintenance",
+            "description": "Human-readable reason for the maintenance (max 500 chars)",
             "nullable": true
           },
           "suppressAlerts": {
@@ -23239,7 +23330,6 @@
       "CreateMonitorRequest": {
         "required": [
           "config",
-          "managedBy",
           "name",
           "type"
         ],
@@ -23286,8 +23376,10 @@
             ]
           },
           "frequencySeconds": {
+            "maximum": 86400,
+            "minimum": 10,
             "type": "integer",
-            "description": "Check frequency in seconds (30–86400); null defaults to plan minimum (60s on most paid plans)",
+            "description": "Check frequency in seconds (10–86400); null defaults to plan minimum (60s on most paid plans)",
             "format": "int32",
             "nullable": true
           },
@@ -23298,20 +23390,23 @@
           },
           "regions": {
             "type": "array",
-            "description": "Probe regions to run checks from, e.g. us-east, eu-west",
+            "description": "Probe regions to run checks from. Allowed values are deployment-dependent; production: us-east, us-west, eu-west, ap-south.",
             "nullable": true,
             "items": {
               "type": "string",
-              "description": "Probe regions to run checks from, e.g. us-east, eu-west"
+              "description": "Probe regions to run checks from. Allowed values are deployment-dependent; production: us-east, us-west, eu-west, ap-south."
             }
           },
           "managedBy": {
             "type": "string",
-            "description": "Who manages this monitor: DASHBOARD or CLI",
+            "description": "Source that created/owns this monitor: DASHBOARD, CLI, TERRAFORM, MCP, or API. Defaults to API when omitted; set to your surface so audit logs, drift detection, and analytics attribute correctly.",
+            "nullable": true,
             "enum": [
               "DASHBOARD",
               "CLI",
-              "TERRAFORM"
+              "TERRAFORM",
+              "MCP",
+              "API"
             ]
           },
           "environmentId": {
@@ -23506,6 +23601,18 @@
             "description": "Recovery cooldown in minutes after group incident resolves (0–60)",
             "format": "int32",
             "nullable": true
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "Source creating this group: DASHBOARD, CLI, TERRAFORM, MCP, or API. Defaults to API when omitted.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         },
         "description": "Request body for creating a resource group"
@@ -23807,6 +23914,18 @@
               "REVIEW",
               "AUTOMATIC"
             ]
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "Source creating this page: DASHBOARD, CLI, TERRAFORM, MCP, or API. Defaults to API when omitted.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         }
       },
@@ -26432,7 +26551,7 @@
           },
           "repeatRule": {
             "type": "string",
-            "description": "iCal RRULE for recurring windows; null for one-time",
+            "description": "Reserved: iCal RRULE for recurring windows (stored but not yet honored)",
             "nullable": true
           },
           "reason": {
@@ -27194,11 +27313,13 @@
           },
           "managedBy": {
             "type": "string",
-            "description": "Management source: DASHBOARD or CLI",
+            "description": "Source that created/owns this monitor: DASHBOARD, CLI, TERRAFORM, MCP, or API",
             "enum": [
               "DASHBOARD",
               "CLI",
-              "TERRAFORM"
+              "TERRAFORM",
+              "MCP",
+              "API"
             ]
           },
           "createdAt": {
@@ -27265,6 +27386,18 @@
               "description": "Alert channel IDs linked to this monitor; populated on single-monitor responses",
               "format": "uuid"
             }
+          },
+          "currentStatus": {
+            "type": "string",
+            "description": "Current operational state — UP, DOWN, DEGRADED, PAUSED, or UNKNOWN if no probe data yet",
+            "nullable": true,
+            "enum": [
+              "up",
+              "degraded",
+              "down",
+              "paused",
+              "unknown"
+            ]
           }
         },
         "description": "Full monitor representation"
@@ -28455,6 +28588,18 @@
               "$ref": "#/components/schemas/ResourceGroupMemberDto"
             }
           },
+          "managedBy": {
+            "type": "string",
+            "description": "Source that created/owns this group: DASHBOARD, CLI, TERRAFORM, MCP, or API. Null on groups created before this attribution column existed.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
+          },
           "createdAt": {
             "type": "string",
             "description": "Timestamp when the group was created",
@@ -28715,6 +28860,7 @@
               "up",
               "degraded",
               "down",
+              "paused",
               "unknown"
             ]
           },
@@ -31050,6 +31196,18 @@
               "UNDER_MAINTENANCE"
             ]
           },
+          "managedBy": {
+            "type": "string",
+            "description": "Source that created/owns this status page: DASHBOARD, CLI, TERRAFORM, MCP, or API. Null on pages created before this attribution column existed.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
+          },
           "createdAt": {
             "type": "string",
             "format": "date-time"
@@ -32993,6 +33151,18 @@
                 "$ref": "#/components/schemas/WebhookChannelConfig"
               }
             ]
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "New attribution source: DASHBOARD, CLI, TERRAFORM, MCP, or API; null preserves current value.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         }
       },
@@ -33233,7 +33403,7 @@
         "properties": {
           "monitorId": {
             "type": "string",
-            "description": "Monitor to attach this maintenance window to; null preserves current",
+            "description": "Monitor this window applies to; null switches the window to org-wide",
             "format": "uuid",
             "nullable": true
           },
@@ -33251,17 +33421,19 @@
             "maxLength": 100,
             "minLength": 0,
             "type": "string",
-            "description": "Updated iCal RRULE; null clears the repeat rule",
+            "description": "Reserved: iCal RRULE for recurring windows (stored but not yet honored); null clears it",
             "nullable": true
           },
           "reason": {
+            "maxLength": 500,
+            "minLength": 0,
             "type": "string",
-            "description": "Updated reason; null clears the existing reason",
+            "description": "Updated reason (max 500 chars); null clears the existing reason",
             "nullable": true
           },
           "suppressAlerts": {
             "type": "boolean",
-            "description": "Whether to suppress alerts; null preserves current",
+            "description": "Whether to suppress alerts during this window; null defaults to true",
             "nullable": true
           }
         }
@@ -33324,8 +33496,10 @@
             ]
           },
           "frequencySeconds": {
+            "maximum": 86400,
+            "minimum": 10,
             "type": "integer",
-            "description": "New check frequency in seconds (30–86400); null preserves current",
+            "description": "New check frequency in seconds (10–86400); null preserves current",
             "format": "int32",
             "nullable": true
           },
@@ -33336,21 +33510,23 @@
           },
           "regions": {
             "type": "array",
-            "description": "New probe regions; null preserves current",
+            "description": "New probe regions; null preserves current. Allowed values are deployment-dependent.",
             "nullable": true,
             "items": {
               "type": "string",
-              "description": "New probe regions; null preserves current"
+              "description": "New probe regions; null preserves current. Allowed values are deployment-dependent."
             }
           },
           "managedBy": {
             "type": "string",
-            "description": "New management source; null preserves current",
+            "description": "New ownership source: DASHBOARD, CLI, TERRAFORM, MCP, or API; null preserves current value",
             "nullable": true,
             "enum": [
               "DASHBOARD",
               "CLI",
-              "TERRAFORM"
+              "TERRAFORM",
+              "MCP",
+              "API"
             ]
           },
           "environmentId": {
@@ -33597,6 +33773,18 @@
             "description": "Recovery cooldown in minutes; null clears",
             "format": "int32",
             "nullable": true
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "New attribution source: DASHBOARD, CLI, TERRAFORM, MCP, or API; null preserves current value.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         },
         "description": "Request body for updating a resource group"
@@ -33801,6 +33989,18 @@
               "REVIEW",
               "AUTOMATIC"
             ]
+          },
+          "managedBy": {
+            "type": "string",
+            "description": "New attribution source: DASHBOARD, CLI, TERRAFORM, MCP, or API; null preserves current value.",
+            "nullable": true,
+            "enum": [
+              "DASHBOARD",
+              "CLI",
+              "TERRAFORM",
+              "MCP",
+              "API"
+            ]
           }
         }
       },

{devhelm_mcp_server-0.7.0 → devhelm_mcp_server-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devhelm-mcp-server"
-version = "0.7.0"
+version = "0.8.2"
 description = "DevHelm MCP server — AI agent access to monitors, incidents, alerting, and more"
 authors = [{ name = "DevHelm", email = "hello@devhelm.io" }]
 license = "MIT"
@@ -19,9 +19,11 @@ classifiers = [
 ]
 
 dependencies = [
-    # Floor bumped to 0.5.0 for the forensic read resource (timeline / trace /
-    # evaluations / transitions / policy snapshot) used by tools/forensics.py.
-    "devhelm>=0.6.0",
+    # Floor bumped to 0.7.2: required for `managedBy` field on resource DTOs
+    # and for the new monitor validation contract (frequencySeconds bounds,
+    # dynamic region whitelist). Older devhelm versions raise Pydantic
+    # `extra_forbidden` errors when the API returns `managedBy`.
+    "devhelm>=0.7.2",
     "fastmcp>=2.0.0",
 ]
 

{devhelm_mcp_server-0.7.0 → devhelm_mcp_server-0.8.2}/src/devhelm_mcp/client.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import os
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
-from typing import Any
+from typing import Any, NoReturn
 
 from devhelm import (
     Devhelm,
@@ -15,6 +15,7 @@ from devhelm import (
     DevhelmTransportError,
     DevhelmValidationError,
 )
+from fastmcp.exceptions import ToolError
 from pydantic import BaseModel
 
 API_BASE_URL = os.getenv("DEVHELM_API_URL", "https://api.devhelm.io")
@@ -201,6 +202,26 @@ def format_error(err: DevhelmError) -> str:
     return f"Error: {err}"
 
 
+def raise_tool_error(err: DevhelmError) -> NoReturn:
+    """Convert an SDK error into a FastMCP ``ToolError`` so ``isError=true``.
+
+    Per the MCP spec, upstream API failures must surface as
+    ``CallToolResult.isError = true`` so the LLM can distinguish a tool that
+    *ran but failed* from one that *succeeded with an error message in the
+    response* — those have the same shape on the wire otherwise.
+
+    The previous behavior returned ``format_error(err)`` as a regular tool
+    return value (``isError = false``), which caused agents to confidently
+    report success after a 4xx/5xx (silent-corruption bug from the round-3
+    DevEx audit). FastMCP catches the ``ToolError`` raised here and
+    serializes it into ``CallToolResult(isError=True, content=[...])``,
+    preserving the human-readable formatted message for the LLM.
+
+    See https://modelcontextprotocol.io/specification/server/tools#error-handling.
+    """
+    raise ToolError(format_error(err)) from err
+
+
 JsonValue = dict[str, "JsonValue"] | list["JsonValue"] | str | int | float | bool | None