devhelm-mcp-server 0.1.0__py3-none-any.whl

devhelm_mcp/__init__.py

@@ -0,0 +1 @@
+"""DevHelm MCP Server — AI agent access to monitors, incidents, alerting, and more."""

devhelm_mcp/client.py

@@ -0,0 +1,34 @@
+"""SDK client helpers for tool implementations."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from devhelm import Devhelm, DevhelmError
+
+API_BASE_URL = os.getenv("DEVHELM_API_URL", "https://api.devhelm.io")
+
+
+def get_client(api_token: str) -> Devhelm:
+    """Build a Devhelm SDK client from the user's API token."""
+    return Devhelm(token=api_token, base_url=API_BASE_URL)
+
+
+def format_error(err: DevhelmError) -> str:
+    """Format a DevhelmError into a human-readable message for the LLM."""
+    parts = [f"Error ({err.code}): {err.message}"]
+    if err.detail:
+        parts.append(f"Detail: {err.detail}")
+    return " | ".join(parts)
+
+
+def serialize(data: Any) -> Any:
+    """Serialize Pydantic models or other objects to JSON-safe dicts."""
+    if hasattr(data, "model_dump"):
+        return data.model_dump(mode="json")
+    if isinstance(data, list):
+        return [serialize(item) for item in data]
+    if isinstance(data, dict):
+        return {k: serialize(v) for k, v in data.items()}
+    return data

devhelm_mcp/server.py

@@ -0,0 +1,150 @@
+"""DevHelm MCP Server.
+
+Supports two connection modes:
+  1. Bearer auth at /mcp  — standard MCP client with Authorization header
+  2. API key in path at /{api_key}/mcp — for clients that only accept a URL
+
+Both resolve the token to a Devhelm SDK client per-request.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from devhelm import Devhelm, DevhelmError
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from devhelm_mcp.tools import (
+    alert_channels,
+    api_keys,
+    dependencies,
+    deploy_lock,
+    environments,
+    incidents,
+    monitors,
+    notification_policies,
+    resource_groups,
+    secrets,
+    status,
+    tags,
+    webhooks,
+)
+
+API_BASE_URL = os.getenv("DEVHELM_API_URL", "https://api.devhelm.io")
+
+mcp = FastMCP(
+    "DevHelm",
+    instructions=(
+        "DevHelm MCP server for monitoring infrastructure. "
+        "Use these tools to manage uptime monitors, incidents, alert channels, "
+        "notification policies, environments, secrets, tags, resource groups, "
+        "webhooks, API keys, service dependencies, deploy locks, and view "
+        "dashboard status. All operations require a valid DevHelm API token."
+    ),
+)
+
+ALL_TOOL_MODULES = [
+    monitors,
+    incidents,
+    alert_channels,
+    notification_policies,
+    environments,
+    secrets,
+    tags,
+    resource_groups,
+    webhooks,
+    api_keys,
+    dependencies,
+    deploy_lock,
+    status,
+]
+
+for mod in ALL_TOOL_MODULES:
+    mod.register(mcp)
+
+
+def _get_client(token: str) -> Devhelm:
+    return Devhelm(token=token, base_url=API_BASE_URL)
+
+
+def _error_response(err: DevhelmError) -> dict[str, Any]:
+    return {"error": err.code, "message": err.message, "status": err.status}
+
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health(request: Request) -> JSONResponse:
+    return JSONResponse({"status": "healthy", "service": "devhelm-mcp-server"})
+
+
+def _get_app():
+    """Build the ASGI app with path-based auth routing."""
+    from starlette.applications import Starlette
+    from starlette.middleware import Middleware
+    from starlette.middleware.cors import CORSMiddleware
+    from starlette.routing import Mount, Route
+
+    mcp_app = mcp.http_app(path="/mcp")
+
+    async def health_handler(request: Request) -> JSONResponse:
+        return JSONResponse({"status": "healthy", "service": "devhelm-mcp-server"})
+
+    async def path_auth_handler(request: Request) -> JSONResponse:
+        """Handle /{api_key}/mcp/* — extract token from path, proxy to MCP app."""
+        api_key = request.path_params["api_key"]
+        scope = dict(request.scope)
+        original_path: str = scope.get("path", "")
+        prefix = f"/{api_key}"
+        if original_path.startswith(prefix):
+            scope["path"] = original_path[len(prefix) :]
+        scope["headers"] = [
+            *[(k, v) for k, v in scope.get("headers", []) if k != b"authorization"],
+            (b"authorization", f"Bearer {api_key}".encode()),
+        ]
+        from starlette.requests import Request as StarletteRequest
+
+        inner_request = StarletteRequest(scope, request.receive)
+        response = await mcp_app(inner_request.scope, inner_request.receive, None)  # type: ignore[arg-type]
+        return response  # type: ignore[return-value]
+
+    middleware = [
+        Middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+        ),
+    ]
+
+    app = Starlette(
+        routes=[
+            Route("/health", health_handler, methods=["GET"]),
+            Mount("/mcp", app=mcp_app),
+            Mount("/{api_key}/mcp", app=mcp_app),
+        ],
+        middleware=middleware,
+    )
+    return app
+
+
+app = _get_app()
+
+
+def main() -> None:
+    """Entry point for production: uvicorn devhelm_mcp.server:app"""
+    import uvicorn
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run(
+        "devhelm_mcp.server:app",
+        host=host,
+        port=port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

devhelm_mcp/tools/alert_channels.py

@@ -0,0 +1,70 @@
+"""Alert channel tools — Slack, email, webhook, and other notification channels."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_alert_channels(api_token: str) -> Any:
+        """List all alert channels configured in the workspace."""
+        try:
+            return serialize(get_client(api_token).alert_channels.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_alert_channel(api_token: str, channel_id: str) -> Any:
+        """Get an alert channel by ID."""
+        try:
+            return serialize(get_client(api_token).alert_channels.get(channel_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_alert_channel(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a new alert channel.
+
+        Required: name, type, config (type-specific).
+        Types: SLACK, EMAIL, WEBHOOK, PAGERDUTY, OPSGENIE,
+        TELEGRAM, DISCORD, MSTEAMS.
+        """
+        try:
+            return serialize(get_client(api_token).alert_channels.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_alert_channel(
+        api_token: str, channel_id: str, body: dict[str, Any]
+    ) -> Any:
+        """Update an existing alert channel."""
+        try:
+            return serialize(
+                get_client(api_token).alert_channels.update(channel_id, body)
+            )
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_alert_channel(api_token: str, channel_id: str) -> str:
+        """Delete an alert channel."""
+        try:
+            get_client(api_token).alert_channels.delete(channel_id)
+            return "Alert channel deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def test_alert_channel(api_token: str, channel_id: str) -> Any:
+        """Send a test notification to an alert channel to verify it works."""
+        try:
+            return serialize(get_client(api_token).alert_channels.test(channel_id))
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/api_keys.py

@@ -0,0 +1,49 @@
+"""API key tools — manage API keys for programmatic access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_api_keys(api_token: str) -> Any:
+        """List all API keys in the workspace."""
+        try:
+            return serialize(get_client(api_token).api_keys.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_api_key(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a new API key. The key value is returned only once.
+
+        Required fields: name. Optional: expiresAt.
+        """
+        try:
+            return serialize(get_client(api_token).api_keys.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def revoke_api_key(api_token: str, key_id: str) -> str:
+        """Revoke an API key (disables it without deleting)."""
+        try:
+            get_client(api_token).api_keys.revoke(key_id)
+            return "API key revoked successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_api_key(api_token: str, key_id: str) -> str:
+        """Delete an API key permanently."""
+        try:
+            get_client(api_token).api_keys.delete(key_id)
+            return "API key deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/dependencies.py

@@ -0,0 +1,45 @@
+"""Dependency tools — track third-party service dependencies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_dependencies(api_token: str) -> Any:
+        """List all tracked service dependencies."""
+        try:
+            return serialize(get_client(api_token).dependencies.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_dependency(api_token: str, dependency_id: str) -> Any:
+        """Get a tracked dependency by ID."""
+        try:
+            return serialize(get_client(api_token).dependencies.get(dependency_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def track_dependency(api_token: str, slug: str) -> Any:
+        """Start tracking a service dependency by its slug (e.g. 'github', 'aws')."""
+        try:
+            return serialize(get_client(api_token).dependencies.track(slug))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_dependency(api_token: str, dependency_id: str) -> str:
+        """Stop tracking a service dependency."""
+        try:
+            get_client(api_token).dependencies.delete(dependency_id)
+            return "Dependency removed successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/deploy_lock.py

@@ -0,0 +1,50 @@
+"""Deploy lock tools — coordinate safe deployments."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def acquire_deploy_lock(api_token: str, body: dict[str, Any]) -> Any:
+        """Acquire a deploy lock to prevent concurrent deployments.
+
+        Required fields: reason. Optional: ttlSeconds.
+        """
+        try:
+            return serialize(get_client(api_token).deploy_lock.acquire(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_current_deploy_lock(api_token: str) -> Any:
+        """Get the currently active deploy lock, or null if unlocked."""
+        try:
+            result = get_client(api_token).deploy_lock.current()
+            return serialize(result) if result else None
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def release_deploy_lock(api_token: str, lock_id: str) -> str:
+        """Release a deploy lock by ID."""
+        try:
+            get_client(api_token).deploy_lock.release(lock_id)
+            return "Deploy lock released."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def force_release_deploy_lock(api_token: str) -> str:
+        """Force-release any active deploy lock (admin action)."""
+        try:
+            get_client(api_token).deploy_lock.force_release()
+            return "Deploy lock force-released."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/environments.py

@@ -0,0 +1,56 @@
+"""Environment tools — prod, staging, and custom environment grouping."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_environments(api_token: str) -> Any:
+        """List all environments in the workspace."""
+        try:
+            return serialize(get_client(api_token).environments.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_environment(api_token: str, slug: str) -> Any:
+        """Get an environment by slug (e.g. 'production', 'staging')."""
+        try:
+            return serialize(get_client(api_token).environments.get(slug))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_environment(api_token: str, body: dict[str, Any]) -> Any:
+        """Create an environment.
+
+        Required fields: name, slug, color.
+        """
+        try:
+            return serialize(get_client(api_token).environments.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_environment(api_token: str, slug: str, body: dict[str, Any]) -> Any:
+        """Update an environment by slug."""
+        try:
+            return serialize(get_client(api_token).environments.update(slug, body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_environment(api_token: str, slug: str) -> str:
+        """Delete an environment by slug."""
+        try:
+            get_client(api_token).environments.delete(slug)
+            return "Environment deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/incidents.py

@@ -0,0 +1,61 @@
+"""Incident tools — manual and auto-detected incidents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_incidents(api_token: str) -> Any:
+        """List all incidents in the workspace."""
+        try:
+            return serialize(get_client(api_token).incidents.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_incident(api_token: str, incident_id: str) -> Any:
+        """Get a single incident by ID with full details."""
+        try:
+            return serialize(get_client(api_token).incidents.get(incident_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_incident(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a manual incident.
+
+        Required fields: monitorId, severity (CRITICAL/HIGH/MEDIUM/LOW).
+        Optional: message.
+        """
+        try:
+            return serialize(get_client(api_token).incidents.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def resolve_incident(
+        api_token: str, incident_id: str, message: str | None = None
+    ) -> Any:
+        """Resolve an active incident, optionally with a resolution message."""
+        try:
+            return serialize(
+                get_client(api_token).incidents.resolve(incident_id, message)
+            )
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_incident(api_token: str, incident_id: str) -> str:
+        """Delete an incident permanently."""
+        try:
+            get_client(api_token).incidents.delete(incident_id)
+            return "Incident deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/monitors.py

@@ -0,0 +1,112 @@
+"""Monitor tools — HTTP, DNS, TCP, ICMP, MCP, and Heartbeat monitors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_monitors(api_token: str) -> Any:
+        """List all uptime monitors in the workspace."""
+        try:
+            return serialize(get_client(api_token).monitors.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_monitor(api_token: str, monitor_id: str) -> Any:
+        """Get a single monitor by ID, including its full configuration."""
+        try:
+            return serialize(get_client(api_token).monitors.get(monitor_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_monitor(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a new uptime monitor.
+
+        Required fields: name, type (HTTP/DNS/TCP/ICMP/MCP/HEARTBEAT),
+        config (type-specific), frequencySeconds (30-86400).
+        """
+        try:
+            return serialize(get_client(api_token).monitors.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_monitor(api_token: str, monitor_id: str, body: dict[str, Any]) -> Any:
+        """Update an existing monitor's configuration."""
+        try:
+            return serialize(get_client(api_token).monitors.update(monitor_id, body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_monitor(api_token: str, monitor_id: str) -> str:
+        """Delete a monitor permanently."""
+        try:
+            get_client(api_token).monitors.delete(monitor_id)
+            return "Monitor deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def pause_monitor(api_token: str, monitor_id: str) -> Any:
+        """Pause a monitor (stops checking until resumed)."""
+        try:
+            return serialize(get_client(api_token).monitors.pause(monitor_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def resume_monitor(api_token: str, monitor_id: str) -> Any:
+        """Resume a paused monitor."""
+        try:
+            return serialize(get_client(api_token).monitors.resume(monitor_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def test_monitor(api_token: str, monitor_id: str) -> Any:
+        """Trigger an ad-hoc test run for a monitor and return the result."""
+        try:
+            return serialize(get_client(api_token).monitors.test(monitor_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def list_monitor_results(
+        api_token: str,
+        monitor_id: str,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> Any:
+        """List recent check results for a monitor (cursor-paginated)."""
+        try:
+            page = get_client(api_token).monitors.results(
+                monitor_id, cursor=cursor, limit=limit
+            )
+            return serialize({"items": page.items, "next_cursor": page.next_cursor})
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def list_monitor_versions(
+        api_token: str, monitor_id: str, page: int = 0, size: int = 20
+    ) -> Any:
+        """List version history for a monitor."""
+        try:
+            result = get_client(api_token).monitors.versions(
+                monitor_id, page=page, size=size
+            )
+            return serialize(
+                {"items": result.items, "page": result.page, "total": result.total}
+            )
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/notification_policies.py

@@ -0,0 +1,69 @@
+"""Notification policy tools — routing rules for alerts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_notification_policies(api_token: str) -> Any:
+        """List all notification policies in the workspace."""
+        try:
+            return serialize(get_client(api_token).notification_policies.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_notification_policy(api_token: str, policy_id: str) -> Any:
+        """Get a notification policy by ID."""
+        try:
+            return serialize(get_client(api_token).notification_policies.get(policy_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_notification_policy(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a notification policy.
+
+        Required fields: name, monitorIds, channelIds, severity.
+        """
+        try:
+            return serialize(get_client(api_token).notification_policies.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_notification_policy(
+        api_token: str, policy_id: str, body: dict[str, Any]
+    ) -> Any:
+        """Update a notification policy."""
+        try:
+            return serialize(
+                get_client(api_token).notification_policies.update(policy_id, body)
+            )
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_notification_policy(api_token: str, policy_id: str) -> str:
+        """Delete a notification policy."""
+        try:
+            get_client(api_token).notification_policies.delete(policy_id)
+            return "Notification policy deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def test_notification_policy(api_token: str, policy_id: str) -> str:
+        """Send a test dispatch to verify a notification policy's routing."""
+        try:
+            get_client(api_token).notification_policies.test(policy_id)
+            return "Test dispatch sent successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/resource_groups.py

@@ -0,0 +1,86 @@
+"""Resource group tools — logical grouping of monitors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_resource_groups(api_token: str) -> Any:
+        """List all resource groups in the workspace."""
+        try:
+            return serialize(get_client(api_token).resource_groups.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_resource_group(api_token: str, group_id: str) -> Any:
+        """Get a resource group by ID."""
+        try:
+            return serialize(get_client(api_token).resource_groups.get(group_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_resource_group(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a resource group.
+
+        Required fields: name. Optional: description.
+        """
+        try:
+            return serialize(get_client(api_token).resource_groups.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_resource_group(
+        api_token: str, group_id: str, body: dict[str, Any]
+    ) -> Any:
+        """Update a resource group."""
+        try:
+            return serialize(
+                get_client(api_token).resource_groups.update(group_id, body)
+            )
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_resource_group(api_token: str, group_id: str) -> str:
+        """Delete a resource group."""
+        try:
+            get_client(api_token).resource_groups.delete(group_id)
+            return "Resource group deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def add_resource_group_member(
+        api_token: str, group_id: str, body: dict[str, Any]
+    ) -> Any:
+        """Add a monitor to a resource group.
+
+        Required fields: monitorId.
+        """
+        try:
+            return serialize(
+                get_client(api_token).resource_groups.add_member(group_id, body)
+            )
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def remove_resource_group_member(
+        api_token: str, group_id: str, member_id: str
+    ) -> str:
+        """Remove a monitor from a resource group."""
+        try:
+            get_client(api_token).resource_groups.remove_member(group_id, member_id)
+            return "Member removed from resource group."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/secrets.py

@@ -0,0 +1,49 @@
+"""Secret tools — encrypted secrets for monitor authentication."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_secrets(api_token: str) -> Any:
+        """List all secrets (metadata only, values are never returned)."""
+        try:
+            return serialize(get_client(api_token).secrets.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_secret(api_token: str, body: dict[str, Any]) -> Any:
+        """Create an encrypted secret.
+
+        Required fields: key, value. The value is encrypted at rest
+        and can be referenced in monitor auth configs as {{secrets.KEY}}.
+        """
+        try:
+            return serialize(get_client(api_token).secrets.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_secret(api_token: str, key: str, body: dict[str, Any]) -> Any:
+        """Update a secret's value by key."""
+        try:
+            return serialize(get_client(api_token).secrets.update(key, body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_secret(api_token: str, key: str) -> str:
+        """Delete a secret by key."""
+        try:
+            get_client(api_token).secrets.delete(key)
+            return "Secret deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/status.py

@@ -0,0 +1,21 @@
+"""Status tools — dashboard overview."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def get_status_overview(api_token: str) -> Any:
+        """Get the dashboard overview with monitor counts,
+        incident summary, and uptime stats."""
+        try:
+            return serialize(get_client(api_token).status.overview())
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/tags.py

@@ -0,0 +1,56 @@
+"""Tag tools — organize monitors with tags."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_tags(api_token: str) -> Any:
+        """List all tags in the workspace."""
+        try:
+            return serialize(get_client(api_token).tags.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_tag(api_token: str, tag_id: str) -> Any:
+        """Get a tag by ID."""
+        try:
+            return serialize(get_client(api_token).tags.get(tag_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_tag(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a tag.
+
+        Required fields: name. Optional: color.
+        """
+        try:
+            return serialize(get_client(api_token).tags.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_tag(api_token: str, tag_id: str, body: dict[str, Any]) -> Any:
+        """Update a tag."""
+        try:
+            return serialize(get_client(api_token).tags.update(tag_id, body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_tag(api_token: str, tag_id: str) -> str:
+        """Delete a tag."""
+        try:
+            get_client(api_token).tags.delete(tag_id)
+            return "Tag deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp/tools/webhooks.py

@@ -0,0 +1,64 @@
+"""Webhook tools — outgoing webhook endpoint management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devhelm import DevhelmError
+from fastmcp import FastMCP
+
+from devhelm_mcp.client import format_error, get_client, serialize
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def list_webhooks(api_token: str) -> Any:
+        """List all webhook endpoints in the workspace."""
+        try:
+            return serialize(get_client(api_token).webhooks.list())
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def get_webhook(api_token: str, webhook_id: str) -> Any:
+        """Get a webhook endpoint by ID."""
+        try:
+            return serialize(get_client(api_token).webhooks.get(webhook_id))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def create_webhook(api_token: str, body: dict[str, Any]) -> Any:
+        """Create a webhook endpoint.
+
+        Required fields: url, events (list of event types to subscribe to).
+        """
+        try:
+            return serialize(get_client(api_token).webhooks.create(body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def update_webhook(api_token: str, webhook_id: str, body: dict[str, Any]) -> Any:
+        """Update a webhook endpoint."""
+        try:
+            return serialize(get_client(api_token).webhooks.update(webhook_id, body))
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def delete_webhook(api_token: str, webhook_id: str) -> str:
+        """Delete a webhook endpoint."""
+        try:
+            get_client(api_token).webhooks.delete(webhook_id)
+            return "Webhook deleted successfully."
+        except DevhelmError as e:
+            return format_error(e)
+
+    @mcp.tool()
+    def test_webhook(api_token: str, webhook_id: str) -> Any:
+        """Send a test event to a webhook endpoint to verify it works."""
+        try:
+            return serialize(get_client(api_token).webhooks.test(webhook_id))
+        except DevhelmError as e:
+            return format_error(e)

devhelm_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: devhelm-mcp-server
+Version: 0.1.0
+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
+Project-URL: Documentation, https://docs.devhelm.io
+Author-email: DevHelm <hello@devhelm.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,devhelm,mcp,model-context-protocol,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+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.1.0
+Requires-Dist: fastmcp>=2.0.0
+Description-Content-Type: text/markdown
+
+# DevHelm MCP Server
+
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [DevHelm](https://devhelm.io) — gives AI coding assistants (Cursor, Claude Desktop, Windsurf, etc.) access to your uptime monitors, incidents, alerting, and more.
+
+## Quick Start
+
+### Hosted (recommended)
+
+Use the hosted server at `mcp.devhelm.io`. Two connection modes:
+
+**Bearer auth:**
+```
+URL: https://mcp.devhelm.io/mcp
+Authorization: Bearer <your-api-token>
+```
+
+**API key in URL** (for clients that only accept a URL):
+```
+URL: https://mcp.devhelm.io/<your-api-token>/mcp
+```
+
+### Local (stdio)
+
+```bash
+pip install devhelm-mcp-server
+export DEVHELM_API_TOKEN=your-token
+devhelm-mcp
+```
+
+### Cursor / Claude Desktop
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "devhelm": {
+      "url": "https://mcp.devhelm.io/<your-api-token>/mcp"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Category | Tools |
+|----------|-------|
+| **Monitors** | list, get, create, update, delete, pause, resume, test, results, versions |
+| **Incidents** | list, get, create, resolve, delete |
+| **Alert Channels** | list, get, create, update, delete, test |
+| **Notification Policies** | list, get, create, update, delete, test |
+| **Environments** | list, get, create, update, delete |
+| **Secrets** | list, create, update, delete |
+| **Tags** | list, get, create, update, delete |
+| **Resource Groups** | list, get, create, update, delete, add member, remove member |
+| **Webhooks** | list, get, create, update, delete, test |
+| **API Keys** | list, create, revoke, delete |
+| **Dependencies** | list, get, track, delete |
+| **Deploy Lock** | acquire, current, release, force-release |
+| **Status** | overview |
+
+## Development
+
+```bash
+uv sync
+make dev          # Start with MCP Inspector (stdio)
+make serve        # Start HTTP server on :8000
+make test         # Run unit tests
+make lint         # Check formatting
+make typecheck    # Run mypy
+```
+
+## License
+
+MIT

devhelm_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+devhelm_mcp/__init__.py,sha256=oeWh01V0ettPmXAYkfEbHIp7OjSnjbcn8FarAiJeizk,89
+devhelm_mcp/client.py,sha256=hOnPosQwzQA5jdktPIvX6FepkjSDa9iBbSGx3H9af3w,1043
+devhelm_mcp/server.py,sha256=tX2y32fDN7HYOm1NwKCuaNbmgcyzB4_5_tPhbao4EG4,4140
+devhelm_mcp/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devhelm_mcp/tools/alert_channels.py,sha256=Sm26AGa2KLV3-AtkNZ85AB2m7lcQZbGwVvMzldqsAWY,2389
+devhelm_mcp/tools/api_keys.py,sha256=W9l53NYOfAwzCOqL2KWI8_GwgTQdmb4v7w_Ao9-5QM4,1577
+devhelm_mcp/tools/dependencies.py,sha256=hoM7-bw2GW3pvtnLoTkgxxBiGROqiyW8GH3zNEW837o,1528
+devhelm_mcp/tools/deploy_lock.py,sha256=6NGSMWonp3_k2UmBJWqwrdq1B6cecL7y-teveOtzJhU,1670
+devhelm_mcp/tools/environments.py,sha256=TO2giEYoO3kmjuQWjZQgetqjNRb3Ky6-AM0JVqTstm0,1858
+devhelm_mcp/tools/incidents.py,sha256=AeyxqHrpU69EO_R0UEPPYn_Q5gu0n-WRBi4-qCIgZqU,1987
+devhelm_mcp/tools/monitors.py,sha256=YkwDIWo_CIIoPDqnM48vIiaNg3RKNOaxmq8_TMLhP6s,3929
+devhelm_mcp/tools/notification_policies.py,sha256=Q0DXTgylzuAprVH6Y2fmRz2LFrfi0hCNPp51PER4vLQ,2397
+devhelm_mcp/tools/resource_groups.py,sha256=b58FsTRx9UGi4kCPx9MOeC9Ncapn3j63eSr7zsTBfMc,2745
+devhelm_mcp/tools/secrets.py,sha256=2Ql5Ijk7VTXpcBToQwhQ5bbK71Eak7XlbG5Sqzga0gI,1614
+devhelm_mcp/tools/status.py,sha256=0aUXHnhVa5i0DrmTHR358eNLxxO3MQqmqONVpE23_Lo,597
+devhelm_mcp/tools/tags.py,sha256=dNfsT6GC49MTahR48V0ztgCXOfs296QnUfvyVaHFZZc,1666
+devhelm_mcp/tools/webhooks.py,sha256=PGesOmYP7EggC7LP66hlNULF4pQGVZK2HISa4I3bEXc,2153
+devhelm_mcp_server-0.1.0.dist-info/METADATA,sha256=2mYubQ1qYE9X93Qq2iftZ-worDYr3HRgOZtX7TTlMZs,2938
+devhelm_mcp_server-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+devhelm_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=_6LMWTOaUxcHfZrXbMpfVarUNYdksit4lQmiMD1_Fo8,56
+devhelm_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=z9qxDQi8GcvrzblluNus8VeTsTHcq4tLnTcoh5pTtAk,1064
+devhelm_mcp_server-0.1.0.dist-info/RECORD,,

devhelm_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devhelm_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devhelm-mcp = devhelm_mcp.server:main

devhelm_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevHelm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.