fettle-mcp 0.2.0 → 0.4.0

package/README.md

@@ -96,24 +96,96 @@ claude mcp add fettle --env FETTLE_API_KEY=fettle_your_key_here -- npx -y fettle
 
 ## Tools
 
-| Tool                       | Scope | What it does                                                                            |
-| -------------------------- | ----- | --------------------------------------------------------------------------------------- |
-| `list_monitors`            | read  | List the monitors in the organization the API key belongs to.                           |
-| `list_tags`                | read  | List every tag in the organization with how many monitors and heartbeats carry it.      |
-| `get_monitor`              | read  | Read one monitor's full configuration and current status by id.                         |
-| `create_monitor`           | write | Create a monitor that checks a URL, host or port on a schedule.                         |
-| `update_monitor`           | write | Change an existing monitor's settings.                                                  |
-| `pause_monitor`            | write | Stop checking a monitor without deleting it — use before planned downtime.              |
-| `resume_monitor`           | write | Resume checks on a paused monitor.                                                      |
-| `delete_monitor`           | write | Soft-delete a monitor: it stops being checked and leaves the monitor list.              |
-| `check_now`                | write | Re-arm a monitor to run on the next scheduler tick instead of waiting out its interval. |
-| `bulk_update_monitor_tags` | write | Add and/or remove tags across up to 300 monitors in one call.                           |
-| `get_uptime_summary`       | read  | Uptime, average response time and incident counts over 24h / 7d / 30d at once.          |
-| `list_incidents`           | read  | List incidents, optionally filtered by monitor, status, cause or period.                |
-| `acknowledge_incident`     | write | Acknowledge an open incident so repeat notifications stop.                              |
-| `list_heartbeats`          | read  | List heartbeat (cron / dead-man's-switch) monitors and when each was last pinged.       |
-| `create_heartbeat`         | write | Create a heartbeat monitor and get the URL a scheduled job should ping.                 |
-| `list_status_pages`        | read  | List status pages, with each page's slug and whether it is published.                   |
+49 tools, grouped by what they work on. Read-scope keys can call the `read` ones; everything marked `write` needs a write-scope key.
+
+### Monitors
+
+| Tool                       | Scope | What it does                                                                                  |
+| -------------------------- | ----- | --------------------------------------------------------------------------------------------- |
+| `list_monitors`            | read  | List monitors compactly (status, target, tags, SSL expiry), filtered by type, status, tags.   |
+| `get_monitor`              | read  | Read one monitor's full configuration and current status by id.                               |
+| `check_target`             | write | Probe a target once from one region before creating a monitor for it.                         |
+| `create_monitor`           | write | Create a monitor that checks a URL, host or port on a schedule.                               |
+| `bulk_create_monitors`     | write | Create up to 100 monitors in one call — all of them or none.                                  |
+| `update_monitor`           | write | Change an existing monitor's settings.                                                        |
+| `bulk_update_monitors`     | write | Set the same interval, regions, channels or thresholds on up to 100 monitors, all or nothing. |
+| `pause_monitor`            | write | Stop checking a monitor without deleting it — use before planned downtime.                    |
+| `bulk_pause_monitors`      | write | Pause up to 100 monitors in one call, all or nothing.                                         |
+| `resume_monitor`           | write | Resume checks on a paused monitor.                                                            |
+| `bulk_resume_monitors`     | write | Resume up to 100 paused monitors in one call, all or nothing.                                 |
+| `delete_monitor`           | write | Soft-delete a monitor: it stops being checked and leaves the monitor list.                    |
+| `check_now`                | write | Re-arm a monitor to run on the next scheduler tick instead of waiting out its interval.       |
+| `get_exposed_ports_preset` | read  | Database and admin ports that should not be reachable from the internet.                      |
+
+### Results and uptime
+
+| Tool                          | Scope | What it does                                                                               |
+| ----------------------------- | ----- | ------------------------------------------------------------------------------------------ |
+| `get_uptime_summary`          | read  | Uptime, average response time and incident counts over 24h / 7d / 30d at once.             |
+| `get_uptime_daily`            | read  | A monitor's uptime for each UTC day, oldest first.                                         |
+| `get_response_time_by_region` | read  | A monitor's average response time over 24h, 7d or 30d, one series per region.              |
+| `list_check_results`          | read  | Individual check results of a monitor, newest first, filtered by region, status or period. |
+
+### Incidents
+
+| Tool                   | Scope | What it does                                                             |
+| ---------------------- | ----- | ------------------------------------------------------------------------ |
+| `list_incidents`       | read  | List incidents, optionally filtered by monitor, status, cause or period. |
+| `get_incident`         | read  | Read one incident with its cause and every alert attempt.                |
+| `acknowledge_incident` | write | Acknowledge an open incident so repeat notifications stop.               |
+
+### Heartbeats
+
+| Tool               | Scope | What it does                                                                      |
+| ------------------ | ----- | --------------------------------------------------------------------------------- |
+| `list_heartbeats`  | read  | List heartbeat (cron / dead-man's-switch) monitors and when each was last pinged. |
+| `get_heartbeat`    | read  | Read one heartbeat, including its ping URL and when it will be reported late.     |
+| `create_heartbeat` | write | Create a heartbeat monitor and get the URL a scheduled job should ping.           |
+| `update_heartbeat` | write | Change a heartbeat's name, period, grace, channels or tags.                       |
+| `pause_heartbeat`  | write | Pause a heartbeat: it is not reported late and its pings are ignored.             |
+| `resume_heartbeat` | write | Resume a paused heartbeat.                                                        |
+| `delete_heartbeat` | write | Delete a heartbeat for good; its ping URL stops working.                          |
+
+### Maintenance windows
+
+| Tool                         | Scope | What it does                                                                        |
+| ---------------------------- | ----- | ----------------------------------------------------------------------------------- |
+| `list_maintenance_windows`   | read  | List maintenance windows (one-time or recurring, organization-wide or per monitor). |
+| `list_active_maintenance`    | read  | The maintenance windows in effect right now.                                        |
+| `get_maintenance_window`     | read  | Read one maintenance window with its next three occurrences.                        |
+| `preview_maintenance_window` | write | Show the next three occurrences a schedule would produce, without saving it.        |
+| `create_maintenance_window`  | write | Create a window that silences alerts, once or on an iCal RRULE schedule.            |
+| `update_maintenance_window`  | write | Change a maintenance window.                                                        |
+| `delete_maintenance_window`  | write | Delete a maintenance window; alerts resume at once.                                 |
+
+### Tags
+
+| Tool                       | Scope | What it does                                                                       |
+| -------------------------- | ----- | ---------------------------------------------------------------------------------- |
+| `list_tags`                | read  | List every tag in the organization with how many monitors and heartbeats carry it. |
+| `bulk_update_monitor_tags` | write | Add and/or remove tags across up to 300 monitors in one call.                      |
+| `rename_tag`               | write | Rename a tag on every monitor and heartbeat that carries it.                       |
+| `delete_tag`               | write | Remove a tag from every monitor and heartbeat that carries it.                     |
+
+### Status pages
+
+| Tool                          | Scope | What it does                                                                                  |
+| ----------------------------- | ----- | --------------------------------------------------------------------------------------------- |
+| `list_status_pages`           | read  | List status pages, with each page's slug and whether it is published.                         |
+| `get_status_page`             | read  | Read one status page with its groups and components.                                          |
+| `list_status_page_incidents`  | read  | List a status page's incidents, posted by a person or opened by Fettle, with their timelines. |
+| `create_status_page_incident` | write | Open an incident on a status page with a first message.                                       |
+| `post_status_page_update`     | write | Add a message to a status page incident and set its status; RESOLVED closes it.               |
+| `update_status_page_incident` | write | Rename a status page incident; subscribers are not notified.                                  |
+| `delete_status_page_incident` | write | Remove an incident and its timeline from a status page.                                       |
+
+### Organization and platform
+
+| Tool             | Scope | What it does                                                                |
+| ---------------- | ----- | --------------------------------------------------------------------------- |
+| `get_plan_usage` | read  | The organization's plan, its limits, and how much of each is used.          |
+| `list_channels`  | read  | List notification channels (id, type, label, verified) to bind to monitors. |
+| `list_regions`   | read  | List the check regions and the codes the regions argument takes.            |
 
 The list is not written by hand. It is generated in the Fettle backend from one
 registry and served at
@@ -121,6 +193,63 @@ registry and served at
 this package vendors that file and builds its tools from it at startup, so the
 two MCP channels can never offer different tools.
 
+## Agent guide
+
+The server sends this guide to the client in `initialize` (`instructions`), so an
+agent connected through either channel already has it. It is reproduced here for
+humans and for clients that do not surface server instructions.
+
+<!-- prettier-ignore-start -->
+<!-- agent-guide:start -->
+```text
+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".
+- 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).
+
+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.
+- 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.
+- Exposed ports on a server: follow get_exposed_ports_preset.
+
+MANY MONITORS AT ONCE
+Find 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.
+
+TAGS
+Call 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.
+
+HEARTBEATS
+A 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.
+
+MAINTENANCE
+Before 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.
+
+OUTAGES
+list_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.
+
+ERRORS (start of a failed call's text)
+- "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.
+- "This tool requires/needs an API key with write scope": the key is read-only; tell the user.
+- "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.
+- "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.
+
+```
+<!-- agent-guide:end -->
+<!-- prettier-ignore-end -->
+
 ## The other channel: remote MCP
 
 If your client supports remote MCP servers over HTTP, you do not need this
@@ -159,7 +288,10 @@ There is no OAuth on either channel yet; both authenticate with an API key.
 
 Tool calls spend the same per-organization request budget as the REST API — the
 plan's limit, not a separate one. A rate-limited call comes back saying how many
-seconds to wait. Plan limits are listed at https://fettle.sh/pricing.
+seconds to wait. `check_now` also has its own cap of 10 calls per minute per
+calling address. `get_plan_usage` shows the organization's request budget as
+`limits.api_rate_limit_per_minute`. Plan limits are listed at
+https://fettle.sh/pricing.
 
 ## Troubleshooting
 
@@ -170,7 +302,7 @@ client: most clients read MCP config only at launch.
 **`Authentication failed`** — the key is wrong, revoked, or from a deleted
 organization. Create a fresh one in Settings → API Keys.
 
-**`This tool needs an API key with write scope`** — the key is read-only. Create
+**`This tool requires an API key with write scope`** — the key is read-only. Create
 a write-scoped key; there is no way to widen an existing key's scope.
 
 **The assistant does not see the tools** — restart the client, then confirm