fettle-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Shamanskii
+
+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.

package/README.md

@@ -0,0 +1,171 @@
+# fettle-mcp
+
+MCP server for [Fettle](https://fettle.sh) — uptime monitoring you can drive from
+Claude Code, Claude Desktop, Cursor, Windsurf or anything else that speaks the
+[Model Context Protocol](https://modelcontextprotocol.io).
+
+Ask your assistant to create a monitor, look up why one went down, acknowledge an
+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."
+"Which of my monitors had incidents this week?"
+"Pause the checkout monitor — we're deploying for the next 20 minutes."
+```
+
+## Requirements
+
+- Node.js 20 or newer
+- A Fettle account and an API key (Settings → API Keys at https://fettle.sh)
+
+An API key belongs to one organization and carries either **read** or **write**
+scope. Read-scope keys can list and inspect; the write tools below need a
+write-scope key.
+
+## Install
+
+There is nothing to install — MCP clients run the package with `npx` on demand.
+Add one entry to your client's config and restart it.
+
+### Claude Code
+
+```bash
+claude mcp add fettle --env FETTLE_API_KEY=fettle_your_key_here -- npx -y fettle-mcp
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "fettle": {
+      "command": "npx",
+      "args": ["-y", "fettle-mcp"],
+      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
+
+```json
+{
+  "mcpServers": {
+    "fettle": {
+      "command": "npx",
+      "args": ["-y", "fettle-mcp"],
+      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fettle": {
+      "command": "npx",
+      "args": ["-y", "fettle-mcp"],
+      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable            | Required | Default                 | What it does                                                         |
+| ------------------- | -------- | ----------------------- | -------------------------------------------------------------------- |
+| `FETTLE_API_KEY`    | yes      | —                       | Your API key. The server refuses to start without it.                |
+| `FETTLE_API_URL`    | no       | `https://api.fettle.sh` | Point the server at a different API. You will not normally set this. |
+| `FETTLE_TIMEOUT_MS` | no       | `30000`                 | How long one tool call may take before it is abandoned.              |
+
+## Tools
+
+| Tool                   | Scope | What it does                                                                            |
+| ---------------------- | ----- | --------------------------------------------------------------------------------------- |
+| `list_monitors`        | read  | List the monitors in the organization the API key belongs to.                           |
+| `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. |
+| `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.                   |
+
+The list is not written by hand. It is generated in the Fettle backend from one
+registry and served at
+[`/public-api/mcp-tools.json`](https://api.fettle.sh/public-api/mcp-tools.json);
+this package vendors that file and builds its tools from it at startup, so the
+two MCP channels can never offer different tools.
+
+## The other channel: remote MCP
+
+If your client supports remote MCP servers over HTTP, you do not need this
+package at all — point it at `https://api.fettle.sh/mcp` with the same API key
+as a Bearer token. Same tools, same behaviour, nothing to install or update.
+
+Use this package when your client speaks only stdio, or when you would rather
+the credential stayed in a local config file than in a client's cloud
+configuration.
+
+There is no OAuth on either channel yet; both authenticate with an API key.
+
+## Rate limits and plans
+
+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.
+
+## Troubleshooting
+
+**`FETTLE_API_KEY is not set`** — the client started the server without the
+variable. Check the `env` block of the config above, then fully restart the
+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
+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
+Node.js 20+ with `node -v`. Run `npx -y fettle-mcp` in a terminal: it should
+print the missing-key message and exit, which proves the package itself runs.
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run contract:check        # vendored contract vs. production
+```
+
+Adding a tool is a change in the **backend's** registry, not here: regenerate
+the contract there, then re-vendor it with
+`pnpm run contract:check -- --write` and commit the result. No source file in
+this package describes a tool.
+
+Releasing is documented in [NPM-SETUP.md](./NPM-SETUP.md).
+
+## License
+
+MIT © Mark Shamanskii