@visualsentinel/mcp-server 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to `@visualsentinel/mcp-server`. Format follows [Keep a Changelog](https://keepachangelog.com/) and the package uses [Semantic Versioning](https://semver.org/).
 
+## [0.2.2] - 2026-11-06
+
+### Added
+
+* Four MCP prompts: `check_website_health`, `investigate_broken_site`, `pre_launch_checklist`, `triage_open_incidents`.
+* Three read-only MCP resources: `visualsentinel://plans`, `visualsentinel://help`, `visualsentinel://tools`. The server now advertises the `prompts` and `resources` capabilities.
+* LobeHub badge and homepage link in the README (the LobeHub claim route).
+* `mcpName` is now `com.visualsentinel/mcp-server` (the registry namespace is verified through a DNS record on visualsentinel.com).
+
+### Changed
+
+* `package.json` `homepage` is now https://visualsentinel.com/mcp, so npm and its mirrors link to the product page instead of this repository.
+* Account tools called without an API key now explain that API keys are available on the Business and Agency plans and that the five public tools work without one.
+* `SERVER_VERSION` lives in `src/version.ts`; a test keeps it equal to `package.json`.
+
+## [0.2.1] - 2026-10-16
+
+### Fixed
+
+* `vs_ssl_check` sent `?host=` but the API reads `?domain=`, so every call returned a 400. The tool now takes `domain` (`host` still works as an alias). The unsupported `port` input is removed.
+* `vs_dns_check` sent `recordType`, which the API ignored. It now sends `type`, so the record-type filter works.
+* The server now reports its real version in the MCP handshake instead of a fixed `0.1.0`.
+
+### Added
+
+* Every tool has a `title` and the MCP annotations `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`, as AI directories require.
+* `mcpName` (`io.github.VisualSentinel/mcp-server`) and `server.json` for the official MCP Registry.
+* `.cursor-plugin/plugin.json`, `.claude-plugin/plugin.json`, `.mcp.json` and `mcp.json` for the Cursor Marketplace and Grok Bot, `llms-install.md` for Cline, a `Dockerfile` for the Docker MCP Catalog and Glama, and `gemini-extension.json`.
+
+## [0.2.0] - 2026-06-04
+
+### Added
+
+* New tool `vs_monitors_metrics_bulk`: fetches uptime or response-time metrics for up to 100 monitors in a single API call. Accepts `monitorIds` (array), `metric` (`uptime` | `response-time`), and either a preset `window` or custom `from`+`to` ISO 8601 range. POSTs to `POST /api/monitors/metrics`.
+* `vs_monitors_uptime`: added `from` and `to` input properties for custom date ranges. When both are supplied the handler sends them as query params instead of `period`, allowing arbitrary historical windows.
+* `all` (boolean) input on `vs_monitors_uptime` and `vs_monitors_metrics_bulk`: requests the full available history from the earliest stored data. Precedence mirrors the API: `all` > `from`/`to` > `window`/`period`. This makes the documented full-history capability actually reachable through the tools.
+
+### Changed
+
+* `vs_monitors_uptime`: input schema now includes `from`, `to`, and expands `window` description to list `1h | 6h | 24h | 7d | 30d | 90d | 365d`. Handler now correctly maps `window` → `period` query param (previously `window` was sent as-is and silently ignored by the API). Default period remains `30d`.
+* `tsup.config.ts`: added `src/tools.ts` and `src/api-client.ts` as explicit entry points so they emit separate dist files importable by tests without bundling index.ts.
+
+### Fixed
+
+* `vs_monitors_uptime` handler was sending `{ window: ... }` in the query string instead of `{ period: ... }`. The Visual Sentinel API only accepts `period`; the old behaviour silently fell back to the server default.
+
 ## [0.1.0] - 2026-04-29
 
 Initial public release.

package/README.md

@@ -1,17 +1,20 @@
 # Visual Sentinel MCP Server
 
-Model Context Protocol server for [Visual Sentinel](https://visualsentinel.com), the six-layer website monitoring platform: uptime, performance, SSL, DNS, visual regression, and content change detection.
+[![MCP Badge](https://lobehub.com/badge/mcp/visualsentinel-mcp-server)](https://lobehub.com/mcp/visualsentinel-mcp-server)
 
-Connect Claude Desktop, Claude Code, Cline, Continue, or any MCP-compatible client to your Visual Sentinel account so an AI assistant can list monitors, create them, fetch incident history, run free DNS / SSL / speed checks, and acknowledge alerts on your behalf.
+Model Context Protocol server for [Visual Sentinel](https://visualsentinel.com). Visual Sentinel catches pages that look broken even when the site is up. It monitors six layers: uptime, performance, SSL, DNS, visual regression, and content change.
 
+Connect Claude Desktop, Claude Code, Cursor, Cline, Continue, or any MCP-compatible client so an AI assistant can run DNS, SSL and speed checks on any site with no account. With a Visual Sentinel account and an API key (Business and Agency plans) it can also list and create monitors, fetch incident history, and acknowledge alerts on your behalf.
+
+* **Homepage and docs:** https://visualsentinel.com/mcp
 * **npm:** `@visualsentinel/mcp-server`
 * **OpenAPI spec:** https://github.com/VisualSentinel/openapi
-* **Get an API key:** https://visualsentinel.com/settings/api-keys
+* **API key (Business and Agency plans):** https://visualsentinel.com/settings/api-keys
 * **Hosted API reference:** https://visualsentinel.com/docs
 
 ## What you get
 
-16 tools spanning the public Visual Sentinel API:
+17 tools spanning the public Visual Sentinel API:
 
 **Public tools (no API key required)**
 
@@ -31,7 +34,8 @@ Connect Claude Desktop, Claude Code, Cline, Continue, or any MCP-compatible clie
 | `vs_monitors_get` | `GET /api/monitors/{id}` | Fetch a single monitor with current status |
 | `vs_monitors_create` | `POST /api/monitors` | Create a new monitor |
 | `vs_monitors_check_now` | `POST /api/monitors/{id}/check` | Trigger an immediate check |
-| `vs_monitors_uptime` | `GET /api/monitors/{id}/uptime` | Uptime percentage over 24h / 7d / 30d / 90d / 365d |
+| `vs_monitors_uptime` | `GET /api/monitors/{id}/uptime` | Uptime percentage for a preset window, a custom date range, or the full history |
+| `vs_monitors_metrics_bulk` | `POST /api/monitors/metrics` | Uptime or response-time metrics for up to 100 monitors in one call |
 | `vs_incidents_list` | `GET /api/incidents` | List incidents, filterable by status or monitor |
 | `vs_incidents_get` | `GET /api/incidents/{id}` | Fetch an incident with full check history |
 | `vs_alerts_list` | `GET /api/alerts` | List alerts by status |
@@ -39,6 +43,25 @@ Connect Claude Desktop, Claude Code, Cline, Continue, or any MCP-compatible clie
 | `vs_status_pages_list` | `GET /api/status-pages` | List your public status pages |
 | `vs_servers_list` | `GET /api/servers` | List registered origin servers |
 
+## Prompts and resources
+
+Besides the 17 tools, the server offers four ready-made prompts and three read-only resources. None of them need an API key except the last prompt.
+
+| Prompt | What it does |
+|---|---|
+| `check_website_health` | Runs the website, SSL, DNS and speed checks on one site and summarises what needs attention. |
+| `investigate_broken_site` | Works through DNS, certificate, response and speed to find the layer at fault; reads incidents and alerts too when an API key is set. |
+| `pre_launch_checklist` | Pass, Warn or Fail checklist for a new or migrated domain. |
+| `triage_open_incidents` | Ranks open incidents and unacknowledged alerts (needs an API key). |
+
+| Resource | Contents |
+|---|---|
+| `visualsentinel://plans` | Plan limits, and which plans include API keys and the account tools. |
+| `visualsentinel://help` | Setup without an account, adding an API key, links. |
+| `visualsentinel://tools` | Every tool, whether it needs a key, and whether it changes data. |
+
+Without an API key the server still starts and lists everything. The five public tools work; each account tool returns a clear message that it needs an API key (Business and Agency plans) instead of failing.
+
 ## Installation
 
 ### Claude Desktop
@@ -59,7 +82,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
-Restart Claude Desktop. The 16 tools appear under the tools menu.
+Restart Claude Desktop. The 17 tools appear under the tools menu.
 
 ### Claude Code (CLI)
 
@@ -70,6 +93,30 @@ claude mcp add visualsentinel \
 
 Then export `VS_API_KEY` in the shell where Claude Code runs.
 
+### Cursor and Grok Bot
+
+This repository is also an installable plugin: `.cursor-plugin/plugin.json` and `mcp.json` for the Cursor Marketplace, and `.claude-plugin/plugin.json` and `.mcp.json` for Grok and Claude Code (`grok plugin install VisualSentinel/mcp-server`). Or add the server by hand to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "visualsentinel": {
+      "command": "npx",
+      "args": ["-y", "@visualsentinel/mcp-server"]
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker build -t visualsentinel-mcp-server .
+docker run -i --rm -e VS_API_KEY visualsentinel-mcp-server
+```
+
+The server also ships as a Gemini CLI extension (`gemini-extension.json`).
+
 ### Cline (VS Code extension)
 
 In Cline's MCP settings, add:
@@ -115,7 +162,7 @@ Two environment variables, both optional except in the noted cases:
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `VS_API_KEY` | (none) | Required for the 11 authenticated tools. Public tools work without it. Generate at https://visualsentinel.com/settings/api-keys. |
+| `VS_API_KEY` | (none) | Required for the 12 authenticated tools (API keys are available on the Business and Agency plans). Public tools work without it. Generate at https://visualsentinel.com/settings/api-keys. |
 | `VS_API_BASE` | `https://visualsentinel.com` | Override only for testing against a local development instance. |
 
 If a tool that needs auth is called without `VS_API_KEY`, the server returns a clear error rather than silently failing.

package/dist/api-client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tiny HTTP client for the Visual Sentinel public API.
+ *
+ * Reads the API key from `VS_API_KEY` (or `VISUALSENTINEL_API_KEY`) once at
+ * construction time. All requests are routed at `https://visualsentinel.com`
+ * unless `VS_API_BASE` overrides it (useful for testing against a local
+ * dev instance).
+ */
+interface ApiClientOptions {
+    apiKey?: string | undefined;
+    baseUrl?: string | undefined;
+    userAgent?: string;
+}
+declare class VsApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class ApiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly userAgent;
+    constructor(opts?: ApiClientOptions);
+    hasApiKey(): boolean;
+    request<T = unknown>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, options?: {
+        query?: Record<string, string | number | boolean | undefined>;
+        body?: unknown;
+        auth?: boolean;
+    }): Promise<T>;
+}
+
+export { ApiClient, type ApiClientOptions, VsApiError };

package/dist/api-client.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+// src/api-client.ts
+var DEFAULT_BASE = "https://visualsentinel.com";
+var VsApiError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "VsApiError";
+  }
+  status;
+  body;
+};
+var ApiClient = class {
+  apiKey;
+  baseUrl;
+  userAgent;
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey ?? process.env.VS_API_KEY ?? process.env.VISUALSENTINEL_API_KEY ?? void 0;
+    this.baseUrl = (opts.baseUrl ?? process.env.VS_API_BASE ?? DEFAULT_BASE).replace(
+      /\/+$/,
+      ""
+    );
+    this.userAgent = opts.userAgent ?? "@visualsentinel/mcp-server";
+  }
+  hasApiKey() {
+    return typeof this.apiKey === "string" && this.apiKey.length > 0;
+  }
+  async request(method, path, options = {}) {
+    const auth = options.auth ?? true;
+    if (auth && !this.hasApiKey()) {
+      throw new VsApiError(
+        "This tool needs a Visual Sentinel API key, which is available on the Business and Agency plans. Create one at https://visualsentinel.com/settings/api-keys and set it as VS_API_KEY. The DNS, SSL, speed, website-check and health tools work without a key.",
+        401,
+        null
+      );
+    }
+    const url = new URL(path.startsWith("/") ? path : `/${path}`, this.baseUrl);
+    if (options.query) {
+      for (const [k, v] of Object.entries(options.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = {
+      Accept: "application/json",
+      "User-Agent": this.userAgent
+    };
+    if (auth && this.apiKey) headers["X-API-Key"] = this.apiKey;
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+    });
+    const text = await res.text();
+    let parsed = null;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      throw new VsApiError(
+        `Visual Sentinel API ${method} ${path} returned ${res.status}`,
+        res.status,
+        parsed
+      );
+    }
+    return parsed;
+  }
+};
+export {
+  ApiClient,
+  VsApiError
+};
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-client.ts"],"sourcesContent":["/**\n * Tiny HTTP client for the Visual Sentinel public API.\n *\n * Reads the API key from `VS_API_KEY` (or `VISUALSENTINEL_API_KEY`) once at\n * construction time. All requests are routed at `https://visualsentinel.com`\n * unless `VS_API_BASE` overrides it (useful for testing against a local\n * dev instance).\n */\n\nconst DEFAULT_BASE = 'https://visualsentinel.com';\n\nexport interface ApiClientOptions {\n  apiKey?: string | undefined;\n  baseUrl?: string | undefined;\n  userAgent?: string;\n}\n\nexport class VsApiError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly body: unknown,\n  ) {\n    super(message);\n    this.name = 'VsApiError';\n  }\n}\n\nexport class ApiClient {\n  private readonly apiKey: string | undefined;\n  private readonly baseUrl: string;\n  private readonly userAgent: string;\n\n  constructor(opts: ApiClientOptions = {}) {\n    this.apiKey =\n      opts.apiKey ??\n      process.env.VS_API_KEY ??\n      process.env.VISUALSENTINEL_API_KEY ??\n      undefined;\n    this.baseUrl = (opts.baseUrl ?? process.env.VS_API_BASE ?? DEFAULT_BASE).replace(\n      /\\/+$/,\n      '',\n    );\n    this.userAgent = opts.userAgent ?? '@visualsentinel/mcp-server';\n  }\n\n  hasApiKey(): boolean {\n    return typeof this.apiKey === 'string' && this.apiKey.length > 0;\n  }\n\n  async request<T = unknown>(\n    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',\n    path: string,\n    options: { query?: Record<string, string | number | boolean | undefined>; body?: unknown; auth?: boolean } = {},\n  ): Promise<T> {\n    const auth = options.auth ?? true;\n    if (auth && !this.hasApiKey()) {\n      throw new VsApiError(\n        'This tool needs a Visual Sentinel API key, which is available on the Business and Agency plans. Create one at https://visualsentinel.com/settings/api-keys and set it as VS_API_KEY. The DNS, SSL, speed, website-check and health tools work without a key.',\n        401,\n        null,\n      );\n    }\n\n    const url = new URL(path.startsWith('/') ? path : `/${path}`, this.baseUrl);\n    if (options.query) {\n      for (const [k, v] of Object.entries(options.query)) {\n        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));\n      }\n    }\n\n    const headers: Record<string, string> = {\n      Accept: 'application/json',\n      'User-Agent': this.userAgent,\n    };\n    if (auth && this.apiKey) headers['X-API-Key'] = this.apiKey;\n    if (options.body !== undefined) headers['Content-Type'] = 'application/json';\n\n    const res = await fetch(url, {\n      method,\n      headers,\n      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,\n    });\n\n    const text = await res.text();\n    let parsed: unknown = null;\n    if (text.length > 0) {\n      try {\n        parsed = JSON.parse(text);\n      } catch {\n        parsed = text;\n      }\n    }\n\n    if (!res.ok) {\n      throw new VsApiError(\n        `Visual Sentinel API ${method} ${path} returned ${res.status}`,\n        res.status,\n        parsed,\n      );\n    }\n\n    return parsed as T;\n  }\n}\n"],"mappings":";;;AASA,IAAM,eAAe;AAQd,IAAM,aAAN,cAAyB,MAAM;AAAA,EACpC,YACE,SACgB,QACA,MAChB;AACA,UAAM,OAAO;AAHG;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AAAA,EALkB;AAAA,EACA;AAKpB;AAEO,IAAM,YAAN,MAAgB;AAAA,EACJ;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,OAAyB,CAAC,GAAG;AACvC,SAAK,SACH,KAAK,UACL,QAAQ,IAAI,cACZ,QAAQ,IAAI,0BACZ;AACF,SAAK,WAAW,KAAK,WAAW,QAAQ,IAAI,eAAe,cAAc;AAAA,MACvE;AAAA,MACA;AAAA,IACF;AACA,SAAK,YAAY,KAAK,aAAa;AAAA,EACrC;AAAA,EAEA,YAAqB;AACnB,WAAO,OAAO,KAAK,WAAW,YAAY,KAAK,OAAO,SAAS;AAAA,EACjE;AAAA,EAEA,MAAM,QACJ,QACA,MACA,UAA6G,CAAC,GAClG;AACZ,UAAM,OAAO,QAAQ,QAAQ;AAC7B,QAAI,QAAQ,CAAC,KAAK,UAAU,GAAG;AAC7B,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,UAAM,MAAM,IAAI,IAAI,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI,IAAI,IAAI,KAAK,OAAO;AAC1E,QAAI,QAAQ,OAAO;AACjB,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,QAAQ,KAAK,GAAG;AAClD,YAAI,MAAM,UAAa,MAAM,KAAM,KAAI,aAAa,IAAI,GAAG,OAAO,CAAC,CAAC;AAAA,MACtE;AAAA,IACF;AAEA,UAAM,UAAkC;AAAA,MACtC,QAAQ;AAAA,MACR,cAAc,KAAK;AAAA,IACrB;AACA,QAAI,QAAQ,KAAK,OAAQ,SAAQ,WAAW,IAAI,KAAK;AACrD,QAAI,QAAQ,SAAS,OAAW,SAAQ,cAAc,IAAI;AAE1D,UAAM,MAAM,MAAM,MAAM,KAAK;AAAA,MAC3B;AAAA,MACA;AAAA,MACA,MAAM,QAAQ,SAAS,SAAY,KAAK,UAAU,QAAQ,IAAI,IAAI;AAAA,IACpE,CAAC;AAED,UAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,QAAI,SAAkB;AACtB,QAAI,KAAK,SAAS,GAAG;AACnB,UAAI;AACF,iBAAS,KAAK,MAAM,IAAI;AAAA,MAC1B,QAAQ;AACN,iBAAS;AAAA,MACX;AAAA,IACF;AAEA,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,IAAI;AAAA,QACR,uBAAuB,MAAM,IAAI,IAAI,aAAa,IAAI,MAAM;AAAA,QAC5D,IAAI;AAAA,QACJ;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACF;","names":[]}