fettle-mcp 0.6.1 → 0.7.0

package/README.md

@@ -10,7 +10,7 @@ Ask your assistant to create a monitor, look up why one went down, acknowledge a
 incident or pause checks before a deploy — it calls the same public API you would.
 
 ```
-"Add an HTTP monitor for https://api.acme.dev, check it every minute from all regions."
+"Add an HTTP monitor for https://api.acme.dev, check it every 5 minutes from Europe."
 "Which of my monitors had incidents this week?"
 "Pause the checkout monitor — we're deploying for the next 20 minutes."
 ```
@@ -229,19 +229,21 @@ humans and for clients that do not surface server instructions.
 Fettle is an uptime monitoring service. The tools see only the API key's organization: monitors, heartbeats, maintenance windows, incidents, status page incidents, tags, channels (read), regions. Channels, status pages, members, API keys and billing are managed only in the dashboard (https://dashboard.fettle.sh). Read a tool's description (arguments, limits, errors) before its first call.
 
 FINDING THINGS
-- list_monitors gives one short row per monitor; use it to find ids. Filters are JSON arrays. Broken now: status ["DOWN", "DEGRADED"]. Certificates expiring first: type ["SSL"], sort "ssl_expiry".
+- list_monitors: one short row per monitor, to find ids. Filters are JSON arrays. Broken now: status ["DOWN", "DEGRADED"]. Certificates expiring first: type ["SSL"], sort "ssl_expiry".
 - tag filters lists; tag_match "all" (default) needs every tag, "any" one of them.
-- Lists are paginated: page from 1, size 1..100 (default 25).
+- Pages: page from 1, size 1..100 (default 25).
 
 PLAN LIMITS
 Call get_plan_usage before creating anything: limits (null means none) and usage. A broken limit or an unknown region is a 403 naming it: change the request or tell the user; never retry it unchanged.
 
 CREATING MONITORS
-- check_target probes a target once before create_monitor. list_regions names the region codes.
+- check_target probes a target once before create_monitor.
+- regions: unless the user names some, use every limits.allowed_regions code, up to max_regions; SSL, DNS and port-list TCP take one.
+- After create, tell the user the interval and regions chosen; offer to change the interval (update_monitor).
 - bulk_create_monitors creates up to 100, all or nothing.
 - type and target never change after create.
-- channel_ids: ids from list_channels. Empty or omitted on create alerts every verified, active channel. Email is not a channel: every alert also goes to the account email of whoever created the monitor or heartbeat.
-- update tools change only the fields you pass. Never send null; omit a field to keep it. A monitor's config is replaced whole: send every config field you want to keep.
+- channel_ids: ids from list_channels. Empty or omitted on create alerts every verified, active channel. Email is not a channel: every alert also emails the creator of the monitor or heartbeat.
+- update tools change only the fields you pass; omit one to keep it, never send null. A monitor's config is replaced whole: resend every config field to keep.
 - Exposed ports on a server: follow get_exposed_ports_preset.
 
 MANY MONITORS AT ONCE
@@ -265,7 +267,7 @@ ERRORS (start of a failed call's text)
 - "Invalid argument(s)": names each failing field. "Invalid request:": the rule broken. Fix, retry.
 - "Forbidden:": a plan limit, an unknown region, or the key's user lacks the permission; the reason says which.
 - "Not found:": no such id in this organization.
-- "Rate limited": wait the seconds given, then retry. All API key calls share the organization's per-minute budget.
+- "Rate limited": wait the seconds given, then retry. All API keys share the organization's per-minute budget.
 - "Tool '<name>' failed: the API returned 5xx": server fault, retry once later.
 - "Tool '<name>' does not accept argument(s)": drop the ones named.
 - "Request failed with status N": read the reason, do not retry unchanged.

package/contracts/mcp_tools.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "instructions": "Fettle is an uptime monitoring service. The tools see only the API key's organization: monitors, heartbeats, maintenance windows, incidents, status page incidents, tags, channels (read), regions. Channels, status pages, members, API keys and billing are managed only in the dashboard (https://dashboard.fettle.sh). Read a tool's description (arguments, limits, errors) before its first call.\n\nFINDING THINGS\n- list_monitors gives one short row per monitor; use it to find ids. Filters are JSON arrays. Broken now: status [\"DOWN\", \"DEGRADED\"]. Certificates expiring first: type [\"SSL\"], sort \"ssl_expiry\".\n- tag filters lists; tag_match \"all\" (default) needs every tag, \"any\" one of them.\n- Lists are paginated: page from 1, size 1..100 (default 25).\n\nPLAN LIMITS\nCall get_plan_usage before creating anything: limits (null means none) and usage. A broken limit or an unknown region is a 403 naming it: change the request or tell the user; never retry it unchanged.\n\nCREATING MONITORS\n- check_target probes a target once before create_monitor. list_regions names the region codes.\n- bulk_create_monitors creates up to 100, all or nothing.\n- type and target never change after create.\n- channel_ids: ids from list_channels. Empty or omitted on create alerts every verified, active channel. Email is not a channel: every alert also goes to the account email of whoever created the monitor or heartbeat.\n- update tools change only the fields you pass. Never send null; omit a field to keep it. A monitor's config is replaced whole: send every config field you want to keep.\n- Exposed ports on a server: follow get_exposed_ports_preset.\n\nMANY MONITORS AT ONCE\nFind ids with list_monitors, then bulk_pause_monitors, bulk_resume_monitors or bulk_update_monitors (interval, timeout, regions, channels, threshold, cooldown) for up to 100 ids, all or nothing. bulk_update_monitor_tags adds or removes tags on up to 300. There is no bulk delete.\n\nTAGS\nCall list_tags first and reuse names. Tags are flat labels such as env:prod, trimmed, lowercased and deduplicated; at most 10 per item. rename_tag and delete_tag act on every monitor and heartbeat.\n\nHEARTBEATS\nA job calls ping_url when it succeeds. Job every N seconds, alert after T seconds of silence: period_seconds = N, grace_seconds = T - N. Never late before its first success ping. ping_url + \"/start\" restarts the clock, ping_url + \"/fail\" marks it DOWN at once.\n\nMAINTENANCE\nBefore a deploy or reboot, create_maintenance_window (scope ORG or MONITOR) instead of pausing monitors: checks keep running, but no incident opens and no alert goes out. Not for heartbeats. preview_maintenance_window shows a schedule's next occurrences; list_active_maintenance shows what is silenced now.\n\nOUTAGES\nlist_monitors status [\"DOWN\"] -> list_check_results (status code, error, region per check) -> get_incident. acknowledge_incident stops repeat alerts; the recovery alert still goes out. create_status_page_incident and post_status_page_update can email the page's subscribers: confirm the text with the user first.\n\nERRORS (start of a failed call's text)\n- \"Authentication failed\": the key is missing, revoked or expired, the address is not allowed, or its creator lost access. Do not retry; tell the user.\n- \"This tool requires/needs an API key with write scope\": the key is read-only; tell the user.\n- \"Invalid argument(s)\": names each failing field. \"Invalid request:\": the rule broken. Fix, retry.\n- \"Forbidden:\": a plan limit, an unknown region, or the key's user lacks the permission; the reason says which.\n- \"Not found:\": no such id in this organization.\n- \"Rate limited\": wait the seconds given, then retry. All API key calls share the organization's per-minute budget.\n- \"Tool '<name>' failed: the API returned 5xx\": server fault, retry once later.\n- \"Tool '<name>' does not accept argument(s)\": drop the ones named.\n- \"Request failed with status N\": read the reason, do not retry unchanged.\n",
+  "instructions": "Fettle is an uptime monitoring service. The tools see only the API key's organization: monitors, heartbeats, maintenance windows, incidents, status page incidents, tags, channels (read), regions. Channels, status pages, members, API keys and billing are managed only in the dashboard (https://dashboard.fettle.sh). Read a tool's description (arguments, limits, errors) before its first call.\n\nFINDING THINGS\n- list_monitors: one short row per monitor, to find ids. Filters are JSON arrays. Broken now: status [\"DOWN\", \"DEGRADED\"]. Certificates expiring first: type [\"SSL\"], sort \"ssl_expiry\".\n- tag filters lists; tag_match \"all\" (default) needs every tag, \"any\" one of them.\n- Pages: page from 1, size 1..100 (default 25).\n\nPLAN LIMITS\nCall get_plan_usage before creating anything: limits (null means none) and usage. A broken limit or an unknown region is a 403 naming it: change the request or tell the user; never retry it unchanged.\n\nCREATING MONITORS\n- check_target probes a target once before create_monitor.\n- regions: unless the user names some, use every limits.allowed_regions code, up to max_regions; SSL, DNS and port-list TCP take one.\n- After create, tell the user the interval and regions chosen; offer to change the interval (update_monitor).\n- bulk_create_monitors creates up to 100, all or nothing.\n- type and target never change after create.\n- channel_ids: ids from list_channels. Empty or omitted on create alerts every verified, active channel. Email is not a channel: every alert also emails the creator of the monitor or heartbeat.\n- update tools change only the fields you pass; omit one to keep it, never send null. A monitor's config is replaced whole: resend every config field to keep.\n- Exposed ports on a server: follow get_exposed_ports_preset.\n\nMANY MONITORS AT ONCE\nFind ids with list_monitors, then bulk_pause_monitors, bulk_resume_monitors or bulk_update_monitors (interval, timeout, regions, channels, threshold, cooldown) for up to 100 ids, all or nothing. bulk_update_monitor_tags adds or removes tags on up to 300. There is no bulk delete.\n\nTAGS\nCall list_tags first and reuse names. Tags are flat labels such as env:prod, trimmed, lowercased and deduplicated; at most 10 per item. rename_tag and delete_tag act on every monitor and heartbeat.\n\nHEARTBEATS\nA job calls ping_url when it succeeds. Job every N seconds, alert after T seconds of silence: period_seconds = N, grace_seconds = T - N. Never late before its first success ping. ping_url + \"/start\" restarts the clock, ping_url + \"/fail\" marks it DOWN at once.\n\nMAINTENANCE\nBefore a deploy or reboot, create_maintenance_window (scope ORG or MONITOR) instead of pausing monitors: checks keep running, but no incident opens and no alert goes out. Not for heartbeats. preview_maintenance_window shows a schedule's next occurrences; list_active_maintenance shows what is silenced now.\n\nOUTAGES\nlist_monitors status [\"DOWN\"] -> list_check_results (status code, error, region per check) -> get_incident. acknowledge_incident stops repeat alerts; the recovery alert still goes out. create_status_page_incident and post_status_page_update can email the page's subscribers: confirm the text with the user first.\n\nERRORS (start of a failed call's text)\n- \"Authentication failed\": the key is missing, revoked or expired, the address is not allowed, or its creator lost access. Do not retry; tell the user.\n- \"This tool requires/needs an API key with write scope\": the key is read-only; tell the user.\n- \"Invalid argument(s)\": names each failing field. \"Invalid request:\": the rule broken. Fix, retry.\n- \"Forbidden:\": a plan limit, an unknown region, or the key's user lacks the permission; the reason says which.\n- \"Not found:\": no such id in this organization.\n- \"Rate limited\": wait the seconds given, then retry. All API keys share the organization's per-minute budget.\n- \"Tool '<name>' failed: the API returned 5xx\": server fault, retry once later.\n- \"Tool '<name>' does not accept argument(s)\": drop the ones named.\n- \"Request failed with status N\": read the reason, do not retry unchanged.\n",
   "tools": [
     {
       "name": "list_monitors",
@@ -436,7 +436,7 @@
     {
       "name": "create_monitor",
       "title": "Create a monitor",
-      "description": "Create one monitor that checks a URL, host or port on a schedule from one or more regions, and return it in the get_monitor shape. Use check_target first to catch a typo or an unreachable host; use bulk_create_monitors for several monitors, and create_heartbeat for a job that should report in rather than be probed. Requires a key with the write scope. Plan limits apply (monitor count, minimum interval, monitors faster than 60 seconds, regions per monitor): breaking one is a 403 naming it, so call get_plan_usage first. A paused monitor still counts toward them. An invalid argument is a 422 naming it. Example: {\"name\": \"API\", \"type\": \"HTTP\", \"target\": \"https://api.example.com/health\", \"interval_seconds\": 300, \"timeout_seconds\": 10, \"regions\": [\"eu-central\"], \"config\": {\"expected_status_codes\": [200]}, \"tags\": [\"env:prod\"]}",
+      "description": "Create one monitor that checks a URL, host or port on a schedule from one or more regions, and return it in the get_monitor shape. Use check_target first to catch a typo or an unreachable host; use bulk_create_monitors for several monitors, and create_heartbeat for a job that should report in rather than be probed. Requires a key with the write scope. Plan limits apply (monitor count, minimum interval, monitors faster than 60 seconds, regions per monitor): breaking one is a 403 naming it, so call get_plan_usage first. A paused monitor still counts toward them. An invalid argument is a 422 naming it. The example shows the shape for a plan with one region per monitor; take interval_seconds and regions from the user and get_plan_usage, not from it. Example: {\"name\": \"API\", \"type\": \"HTTP\", \"target\": \"https://api.example.com/health\", \"interval_seconds\": 600, \"timeout_seconds\": 10, \"regions\": [\"us-east\"], \"config\": {\"expected_status_codes\": [200]}, \"tags\": [\"env:prod\"]}",
       "scope": "write",
       "input_schema": {
         "type": "object",
@@ -468,7 +468,7 @@
             "maximum": 86400,
             "minimum": 30,
             "type": "integer",
-            "description": "Seconds between checks, 30 to 86400. The plan sets a minimum (limits.min_interval_seconds) and caps how many monitors may check more often than every 60 seconds (max_fast_monitors); breaking either is a 403 naming the limit."
+            "description": "Seconds between checks, 30 to 86400. The plan sets a minimum (limits.min_interval_seconds) and caps how many monitors may check more often than every 60 seconds (max_fast_monitors); breaking either is a 403 naming the limit. Tell the user the interval you chose."
           },
           "timeout_seconds": {
             "maximum": 120,
@@ -482,7 +482,7 @@
             },
             "minItems": 1,
             "type": "array",
-            "description": "One or more distinct region codes, for example eu-central: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than the plan's max_regions, is a 403. SSL and DNS monitors take exactly one region (422 otherwise)."
+            "description": "One or more distinct region codes: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than max_regions, is a 403. SSL, DNS and TCP monitors with a ports list take exactly one region (422 otherwise). Unless the user names regions, pass every code in limits.allowed_regions, up to the plan's max_regions."
           },
           "config": {
             "additionalProperties": true,
@@ -764,13 +764,13 @@
     {
       "name": "bulk_create_monitors",
       "title": "Create several monitors",
-      "description": "Create 1 to 100 monitors in one call, all or nothing; for a single monitor use create_monitor. Requires a key with the write scope. An invalid item, or a batch that would exceed the plan, rejects the whole call and creates nothing: call get_plan_usage first to check the batch fits. Errors name the failing item. A field that fails validation is named by its path, such as monitors.3.target (index 3 is the fourth item; all such errors are reported at once). Any other item error keeps the status create_monitor would give (403 when its interval or regions break the plan or name an unknown region, 404 for an unknown channel id, 422 for its config or its type's region rules) and its reason starts with monitors[3] (\"<item name>\"): — only the first such item is reported. Read the index only from that leading monitors[N] (the pattern ^monitors\\[(\\d+)\\] after any lead-in such as \"Forbidden: \" or \"Invalid request: \"), never from the name, which may itself contain quotes or brackets. A plan-limit 403 without that prefix is about the batch as a whole: together the items would exceed the plan's monitor count or its quota of monitors below 60 seconds. Fix the item or shrink the batch and send the whole call again. Returns monitors: one list_monitors row per created monitor, in request order. Example: {\"monitors\": [{\"name\": \"db.example.com exposed ports\", \"type\": \"TCP\", \"target\": \"db.example.com\", \"interval_seconds\": 3600, \"timeout_seconds\": 10, \"regions\": [\"eu-central\"], \"config\": {\"ports\": [5432, 6379, 27017], \"expected_state\": \"closed\"}}]}",
+      "description": "Create 1 to 100 monitors in one call, all or nothing; for a single monitor use create_monitor. Requires a key with the write scope. An invalid item, or a batch that would exceed the plan, rejects the whole call and creates nothing: call get_plan_usage first to check the batch fits. Errors name the failing item. A field that fails validation is named by its path, such as monitors.3.target (index 3 is the fourth item; all such errors are reported at once). Any other item error keeps the status create_monitor would give (403 when its interval or regions break the plan or name an unknown region, 404 for an unknown channel id, 422 for its config or its type's region rules) and its reason starts with monitors[3] (\"<item name>\"): — only the first such item is reported. Read the index only from that leading monitors[N] (the pattern ^monitors\\[(\\d+)\\] after any lead-in such as \"Forbidden: \" or \"Invalid request: \"), never from the name, which may itself contain quotes or brackets. A plan-limit 403 without that prefix is about the batch as a whole: together the items would exceed the plan's monitor count or its quota of monitors below 60 seconds. Fix the item or shrink the batch and send the whole call again. Returns monitors: one list_monitors row per created monitor, in request order. The example is a port-list TCP monitor, which takes exactly one region and an interval of at least 300 seconds. Example: {\"monitors\": [{\"name\": \"db.example.com exposed ports\", \"type\": \"TCP\", \"target\": \"db.example.com\", \"interval_seconds\": 3600, \"timeout_seconds\": 10, \"regions\": [\"eu-central\"], \"config\": {\"ports\": [5432, 6379, 27017], \"expected_state\": \"closed\"}}]}",
       "scope": "write",
       "input_schema": {
         "type": "object",
         "properties": {
           "monitors": {
-            "description": "1 to 100 monitors, each taking the same fields and rules as create_monitor's arguments. Items with is_active false are created paused and still count toward the plan.",
+            "description": "1 to 100 monitors, each taking the same fields and rules as create_monitor's arguments. Items with is_active false are created paused and still count toward the plan. Unless the user names regions, give each item every code in limits.allowed_regions, up to the plan's max_regions; tell the user the intervals you chose.",
             "items": {
               "additionalProperties": false,
               "properties": {
@@ -1434,7 +1434,7 @@
             },
             "minItems": 1,
             "type": "array",
-            "description": "One or more distinct region codes, for example eu-central: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than the plan's max_regions, is a 403. SSL and DNS monitors take exactly one region (422 otherwise)."
+            "description": "One or more distinct region codes: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than max_regions, is a 403. SSL, DNS and TCP monitors with a ports list take exactly one region (422 otherwise)."
           },
           "config": {
             "additionalProperties": true,
@@ -2577,7 +2577,7 @@
     {
       "name": "get_uptime_summary",
       "title": "Get uptime for a monitor",
-      "description": "Report one monitor's uptime percentage, average response time and incident count over the last 24 hours, 7 days and 30 days at once, to answer how reliable it has been. For a day-by-day series use get_uptime_daily; for response time per region use get_response_time_by_region; for the individual failures use list_check_results. Returns monitor_id and windows keyed 24h, 7d and 30d, each with uptime_percentage (DEGRADED checks count as up; null when there were no checks), total_checks, up_checks, down_checks, degraded_checks, incident_count and avg_response_time_ms.",
+      "description": "Report one monitor's uptime percentage, average response time and incident count over the last 24 hours, 7 days and 30 days at once, to answer how reliable it has been. For a day-by-day series use get_uptime_daily; for response time per region use get_response_time_by_region; for the individual failures use list_check_results. Returns monitor_id and windows keyed 24h, 7d and 30d, each with uptime_percentage, downtime_seconds, observed_seconds, window_start (later than the window's start when the monitor is younger), total_checks, up_checks, down_checks, degraded_checks, incident_count and avg_response_time_ms. uptime_percentage is the share of observed time outside confirmed outages (an outage counts from the first failing probe to the first probe that is not DOWN; a failure only one region saw does not count; maintenance counts as up; hours with no checks are left out; null when nothing was observed). The check counts are informational: a failed check outside a confirmed outage does not lower uptime_percentage.",
       "scope": "read",
       "input_schema": {
         "type": "object",
@@ -2652,6 +2652,18 @@
                       "type": "null"
                     }
                   ]
+                },
+                "downtime_seconds": {
+                  "description": "Seconds of confirmed downtime inside the window.",
+                  "type": "integer"
+                },
+                "observed_seconds": {
+                  "description": "Seconds inside the window the monitor was observed; uptime is measured over this time. Never less than downtime_seconds.",
+                  "type": "integer"
+                },
+                "window_start": {
+                  "description": "Start of the window: the window length before now, or when the monitor was created if that is later.",
+                  "type": "string"
                 }
               },
               "required": [
@@ -2660,7 +2672,10 @@
                 "up_checks",
                 "down_checks",
                 "incident_count",
-                "avg_response_time_ms"
+                "avg_response_time_ms",
+                "downtime_seconds",
+                "observed_seconds",
+                "window_start"
               ],
               "type": "object"
             },
@@ -5637,7 +5652,7 @@
     {
       "name": "get_uptime_daily",
       "title": "Get a monitor's daily uptime",
-      "description": "Report one monitor's uptime for each UTC day, oldest first and ending today, to find the day an outage or degradation began. Each day has date, uptime_percentage, total_checks, up_checks, down_checks, degraded_checks and maintenance_checks; a degraded check counts as up, and a day with no checks outside maintenance has a null uptime_percentage, not 100. For 24h, 7d and 30d totals use get_uptime_summary. Returns monitor_id and days.",
+      "description": "Report one monitor's uptime for each UTC day, oldest first and ending today, to find the day an outage or degradation began. Each day has date, uptime_percentage, downtime_seconds, observed_seconds, degraded_seconds, total_checks, up_checks, down_checks, degraded_checks and maintenance_checks. degraded_seconds is the day's time in confirmed DEGRADED status (an ongoing degradation counts up to now; 0 for days before this monitor's status history began, when the status ledger shipped); it does not lower uptime_percentage. A day with degraded_seconds above 0 and no confirmed outage is a degraded (yellow) day in the dashboard; degraded_checks alone does not make one. uptime_percentage is the share of the day's observed time outside confirmed outages (an outage counts from the first failing probe to the first probe that is not DOWN; a failure only one region saw does not count; maintenance counts as up; hours with no checks are left out); a day with no checks and no outage has a null uptime_percentage, not 100. The check counts are informational: a failed check outside a confirmed outage does not lower uptime_percentage. For 24h, 7d and 30d totals use get_uptime_summary. Returns monitor_id and days.",
       "scope": "read",
       "input_schema": {
         "type": "object",
@@ -5713,6 +5728,18 @@
                 },
                 "maintenance_checks": {
                   "type": "integer"
+                },
+                "downtime_seconds": {
+                  "description": "Seconds of confirmed downtime inside the day.",
+                  "type": "integer"
+                },
+                "observed_seconds": {
+                  "description": "Seconds of the day the monitor was observed; uptime is measured over this time. Never less than downtime_seconds; 0 means no data.",
+                  "type": "integer"
+                },
+                "degraded_seconds": {
+                  "description": "Seconds of this UTC day the monitor spent in confirmed DEGRADED status (from the monitor's status history; an ongoing degradation counts up to now). Maintenance is not subtracted. Zero for days before this monitor's status history began (when the status ledger shipped).",
+                  "type": "integer"
                 }
               },
               "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fettle-mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "mcpName": "sh.fettle/mcp",
   "description": "Fettle uptime monitoring (https://fettle.sh) for any MCP client — manage monitors, incidents, heartbeats, maintenance windows and status pages from Claude, Cursor or Codex.",
   "keywords": [