fettle-mcp 0.1.0

package/contracts/mcp_tools.json

@@ -0,0 +1,620 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "list_monitors",
+      "title": "List monitors",
+      "description": "List the monitors in the organization the API key belongs to. Use this first to find a monitor's id before any other monitor tool.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "size": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "q": {
+            "maxLength": 255,
+            "type": "string"
+          },
+          "sort": {
+            "enum": [
+              "status",
+              "up_first",
+              "name",
+              "newest",
+              "oldest"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/monitors",
+        "path_params": [],
+        "query": [
+          "page",
+          "size",
+          "q",
+          "sort"
+        ],
+        "body": false
+      }
+    },
+    {
+      "name": "get_monitor",
+      "title": "Get a monitor",
+      "description": "Read one monitor's full configuration and current status by id.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/monitors/{monitor_id}",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "create_monitor",
+      "title": "Create a monitor",
+      "description": "Create a monitor that checks a URL, host or port on a schedule. config's shape depends on type: HTTP takes method, expected_status_codes, follow_redirects, verify_ssl, request_headers, request_body, all optional — omit config for HTTP to use its defaults; PING takes packet_count, optional; SSL takes warn_before_days, port, both optional; TCP requires port (no default) and takes optional expected_state (defaults to OPEN); DNS requires record_type (no default) and takes optional expected_value. Omitting config on a TCP or DNS monitor is rejected with a 422 for the missing field. regions accepts one or more of: eu-central, us-east, ap-southeast — except SSL and DNS monitors, which must target exactly one region (422 otherwise). How many regions a single monitor may use is also capped by plan, as low as 2 on FREE and PLUS. interval_seconds must be at least 30, but lower plans enforce a higher floor: FREE requires at least 120 seconds. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          },
+          "type": {
+            "enum": [
+              "HTTP",
+              "PING",
+              "SSL",
+              "TCP",
+              "DNS"
+            ],
+            "type": "string"
+          },
+          "target": {
+            "maxLength": 2048,
+            "minLength": 1,
+            "type": "string"
+          },
+          "interval_seconds": {
+            "maximum": 86400,
+            "minimum": 30,
+            "type": "integer"
+          },
+          "timeout_seconds": {
+            "maximum": 120,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "regions": {
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "type": "array"
+          },
+          "config": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "confirmation_threshold": {
+            "maximum": 10,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "notification_cooldown_seconds": {
+            "maximum": 86400,
+            "minimum": 60,
+            "type": "integer"
+          },
+          "channel_ids": {
+            "items": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "name",
+          "type",
+          "target",
+          "interval_seconds",
+          "timeout_seconds",
+          "regions"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/monitors",
+        "path_params": [],
+        "query": [],
+        "body": true
+      }
+    },
+    {
+      "name": "update_monitor",
+      "title": "Update a monitor",
+      "description": "Change an existing monitor's settings. Only the fields you pass are modified; at least one field is required, or the request is rejected. config is the exception: passing it replaces the monitor's entire config, not just the keys you include — any field of that type's schema you leave out is reset to its default. Passing only port on a TCP monitor whose expected_state is CLOSED silently resets expected_state to OPEN unless you include it too. config's shape depends on the monitor's type: HTTP takes method, expected_status_codes, follow_redirects, verify_ssl, request_headers, request_body, all optional; PING takes packet_count, optional; SSL takes warn_before_days, port, both optional; TCP requires port (no default) and takes optional expected_state (defaults to OPEN); DNS requires record_type (no default) and takes optional expected_value. regions accepts one or more of: eu-central, us-east, ap-southeast — except SSL and DNS monitors, which must target exactly one region (422 otherwise). How many regions a single monitor may use is also capped by plan, as low as 2 on FREE and PLUS. interval_seconds must be at least 30, but lower plans enforce a higher floor: FREE requires at least 120 seconds. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          },
+          "interval_seconds": {
+            "maximum": 86400,
+            "minimum": 30,
+            "type": "integer"
+          },
+          "timeout_seconds": {
+            "maximum": 120,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "regions": {
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "type": "array"
+          },
+          "config": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "confirmation_threshold": {
+            "maximum": 10,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "notification_cooldown_seconds": {
+            "maximum": 86400,
+            "minimum": 60,
+            "type": "integer"
+          },
+          "channel_ids": {
+            "items": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "badge_enabled": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "PATCH",
+        "path": "/v1/monitors/{monitor_id}",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": true
+      }
+    },
+    {
+      "name": "pause_monitor",
+      "title": "Pause a monitor",
+      "description": "Stop checking a monitor without deleting it — use before planned downtime. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/monitors/{monitor_id}/pause",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "resume_monitor",
+      "title": "Resume a monitor",
+      "description": "Resume checks on a paused monitor. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/monitors/{monitor_id}/resume",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "delete_monitor",
+      "title": "Delete a monitor",
+      "description": "Soft-delete a monitor: it stops being checked and no longer appears in the organization's monitor list. Prefer pause_monitor unless the user explicitly asked for deletion. Requires the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "DELETE",
+        "path": "/v1/monitors/{monitor_id}",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "check_now",
+      "title": "Check a monitor now",
+      "description": "Re-arm a monitor to run on the scheduler's next tick instead of waiting out its interval. Returns the monitor record, not a check result — call get_monitor a moment later to see the outcome. A repeat call for the same monitor within 30 seconds is a silent no-op that returns it unchanged. Across monitors, calls are limited to 10 per minute keyed on the calling address (not the API key or the organization), answering 429 with Retry-After once exceeded — pace yourself if checking many monitors in a row. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/monitors/{monitor_id}/check-now",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "get_uptime_summary",
+      "title": "Get uptime for a monitor",
+      "description": "Uptime percentage, average response time and incident counts for one monitor over the 24-hour, 7-day and 30-day windows at once. Use this to answer 'how reliable has this been'.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "monitor_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/monitors/{monitor_id}/stats",
+        "path_params": [
+          "monitor_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "list_incidents",
+      "title": "List incidents",
+      "description": "List incidents across the organization's monitors, optionally filtered to one monitor, to open or resolved ones, or to a period.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "size": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "monitor_id": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "open",
+              "resolved"
+            ],
+            "type": "string",
+            "description": "Filter by open or resolved; omit for both."
+          },
+          "cause": {
+            "enum": [
+              "TIMEOUT",
+              "DNS_FAILURE",
+              "CONNECTION_REFUSED",
+              "TLS_INVALID",
+              "HTTP_4XX",
+              "HTTP_5XX",
+              "HTTP_UNEXPECTED_STATUS",
+              "KEYWORD_MISSING",
+              "TOO_MANY_REDIRECTS",
+              "TARGET_BLOCKED",
+              "PORT_STATE_MISMATCH",
+              "INVALID_TARGET",
+              "HEARTBEAT_MISSED",
+              "HEARTBEAT_FAILED",
+              "UNKNOWN"
+            ],
+            "type": "string",
+            "description": "Filter by structured failure cause."
+          },
+          "period_days": {
+            "maximum": 365,
+            "minimum": 1,
+            "type": "integer",
+            "description": "Only incidents started within the last N days."
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/incidents",
+        "path_params": [],
+        "query": [
+          "page",
+          "size",
+          "monitor_id",
+          "status",
+          "cause",
+          "period_days"
+        ],
+        "body": false
+      }
+    },
+    {
+      "name": "acknowledge_incident",
+      "title": "Acknowledge an incident",
+      "description": "Acknowledge an open incident so repeat notifications stop while someone works on it. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "incident_id": {
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "incident_id"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/incidents/{incident_id}/acknowledge",
+        "path_params": [
+          "incident_id"
+        ],
+        "query": [],
+        "body": false
+      }
+    },
+    {
+      "name": "list_heartbeats",
+      "title": "List heartbeat monitors",
+      "description": "List heartbeat (cron / dead-man's-switch) monitors and when each was last pinged.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "size": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "q": {
+            "maxLength": 255,
+            "type": "string"
+          },
+          "sort": {
+            "enum": [
+              "status",
+              "name",
+              "created_at"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/heartbeats",
+        "path_params": [],
+        "query": [
+          "page",
+          "size",
+          "q",
+          "sort"
+        ],
+        "body": false
+      }
+    },
+    {
+      "name": "create_heartbeat",
+      "title": "Create a heartbeat monitor",
+      "description": "Create a heartbeat monitor and get back the URL a scheduled job should ping. Requires a key with the write scope.",
+      "scope": "write",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          },
+          "period_seconds": {
+            "maximum": 2592000,
+            "minimum": 60,
+            "type": "integer"
+          },
+          "grace_seconds": {
+            "maximum": 2592000,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "notification_cooldown_seconds": {
+            "maximum": 86400,
+            "minimum": 60,
+            "type": "integer"
+          },
+          "channel_ids": {
+            "items": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "name",
+          "period_seconds",
+          "grace_seconds"
+        ],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "POST",
+        "path": "/v1/heartbeats",
+        "path_params": [],
+        "query": [],
+        "body": true
+      }
+    },
+    {
+      "name": "list_status_pages",
+      "title": "List status pages",
+      "description": "List the organization's status pages, including each page's slug and whether it is currently published.",
+      "scope": "read",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "page": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "size": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "sort": {
+            "enum": [
+              "name",
+              "created_at"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "operation": {
+        "method": "GET",
+        "path": "/v1/status-pages",
+        "path_params": [],
+        "query": [
+          "page",
+          "size",
+          "sort"
+        ],
+        "body": false
+      }
+    }
+  ]
+}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime configuration, read once at startup from the environment.
+ *
+ * An MCP server is spawned by its client with an env block from a JSON config
+ * file the user hand-edits, so a missing or malformed value is the single most
+ * likely failure of this package — and the worst place to discover it is
+ * inside the first tool call, where the model reports it to the user as if the
+ * *monitor* were the problem. Everything here therefore fails at startup, on
+ * stderr, naming the variable and the file to fix.
+ */
+/** Where the public API lives when `FETTLE_API_URL` is not set. */
+export declare const DEFAULT_API_URL = "https://api.fettle.sh";
+/**
+ * How long one tool call may take before it is abandoned.
+ *
+ * A hung request is worse here than a slow one: the MCP client has no timeout
+ * of its own for a stdio server, so an unbounded `fetch` presents to the user
+ * as a permanently frozen assistant. 30s is well past the API's own latency
+ * and well short of a human's patience.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface Config {
+    apiKey: string;
+    apiUrl: string;
+    timeoutMs: number;
+}
+export declare class ConfigError extends Error {
+}
+/**
+ * Build the configuration or explain what is missing.
+ *
+ * Throws:
+ *   ConfigError: `FETTLE_API_KEY` is absent or blank, `FETTLE_API_URL` is not a
+ *   usable http(s) URL, or `FETTLE_TIMEOUT_MS` is not a positive integer.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;