@site-spy/mcp-server 0.0.1

package/README.md

@@ -0,0 +1,85 @@
+# @site-spy/mcp-server
+
+MCP server that lets AI agents monitor websites for changes via [Site Spy](https://sitespy.app).
+
+Track pages, get notified when content changes, view diffs and snapshots — all from your AI assistant.
+
+## Quick Start
+
+Add to your AI client config:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "site-spy": {
+      "command": "npx",
+      "args": ["-y", "@site-spy/mcp-server"],
+      "env": {
+        "SITE_SPY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "site-spy": {
+      "command": "npx",
+      "args": ["-y", "@site-spy/mcp-server"],
+      "env": {
+        "SITE_SPY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Get your API key from [Site Spy Dashboard](https://app.sitespy.app/dashboard) → Settings → API.
+
+If you don't set `SITE_SPY_API_KEY`, the agent will ask you to authenticate interactively.
+
+## Tools
+
+| Tool                 | Description                                            |
+| -------------------- | ------------------------------------------------------ |
+| `authenticate`       | Connect with an API key (if not set via env var)       |
+| `auth_status`        | Check authentication status                            |
+| `list_watches`       | List all monitored websites (optionally filter by tag) |
+| `create_watch`       | Start monitoring a URL for changes                     |
+| `get_watch`          | Get full details of a specific watch                   |
+| `update_watch`       | Update config — pause/resume, change interval, rename  |
+| `delete_watch`       | Stop monitoring and delete a watch                     |
+| `get_change_history` | Get timestamps of detected changes                     |
+| `get_snapshot`       | Get page content at a specific timestamp               |
+| `get_diff`           | Compare content between two timestamps                 |
+| `search_watches`     | Search watches by URL or title                         |
+| `list_tags`          | List all tags for organizing watches                   |
+| `trigger_recheck`    | Force an immediate recheck of all watches              |
+
+## Environment Variables
+
+| Variable            | Description                             | Default                                     |
+| ------------------- | --------------------------------------- | ------------------------------------------- |
+| `SITE_SPY_API_KEY`  | API key for authentication              | — (interactive auth)                        |
+| `SITE_SPY_API_URL`  | Backend API URL                         | `https://detect.coolify.vkuprin.com/api/v1` |
+| `SITE_SPY_AUTH_URL` | URL shown to users for getting API keys | `https://app.sitespy.app/dashboard`         |
+
+## Example Prompts
+
+Once configured, try asking your AI assistant:
+
+- "Monitor https://example.com for changes every 30 minutes"
+- "What websites am I monitoring?"
+- "Show me what changed on my watched pages"
+- "Pause all monitors tagged 'staging'"
+- "Check all my sites right now"
+
+## License
+
+ISC

package/dist/index.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+//#region src/index.ts
+const API_URL = process.env.SITE_SPY_API_URL ?? "https://detect.coolify.vkuprin.com/api/v1";
+const AUTH_URL = process.env.SITE_SPY_AUTH_URL ?? "https://app.sitespy.app/dashboard";
+let apiKey = process.env.SITE_SPY_API_KEY ?? "";
+function requireAuth() {
+	if (!apiKey) throw new Error(`Not authenticated. Ask the user to open ${AUTH_URL} to log in and copy their API key, then call the 'authenticate' tool with it.`);
+}
+async function api(path, opts = {}) {
+	requireAuth();
+	const url = new URL(`${API_URL}${path}`);
+	if (opts.query) {
+		for (const [k, v] of Object.entries(opts.query)) if (v) url.searchParams.set(k, v);
+	}
+	const res = await fetch(url, {
+		method: opts.method ?? "GET",
+		headers: {
+			"x-api-key": apiKey,
+			...opts.body ? { "Content-Type": "application/json" } : {}
+		},
+		body: opts.body ? JSON.stringify(opts.body) : void 0
+	});
+	const text = await res.text();
+	if (!res.ok) throw new Error(`API ${res.status}: ${text}`);
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function jsonContent(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+const server = new McpServer({
+	name: "site-spy",
+	version: "1.0.0"
+});
+server.registerTool("authenticate", {
+	description: `Connect to Site Spy with an API key. If the user doesn't have one, ask them to open ${AUTH_URL} to log in and copy their key from the Settings > API tab.`,
+	inputSchema: z.object({ api_key: z.string().describe("Site Spy API key") })
+}, async ({ api_key }) => {
+	const res = await fetch(`${API_URL}/watch`, { headers: { "x-api-key": api_key } });
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Invalid API key. Please check the key and try again. (${res.status}: ${text})`);
+	}
+	await res.text();
+	apiKey = api_key;
+	return jsonContent({
+		authenticated: true,
+		message: "Connected to Site Spy successfully."
+	});
+});
+server.registerTool("auth_status", {
+	description: "Check whether the MCP server is currently authenticated with Site Spy.",
+	inputSchema: z.object({})
+}, async () => {
+	if (!apiKey) return jsonContent({
+		authenticated: false,
+		auth_url: AUTH_URL,
+		message: `Not connected. Ask the user to open ${AUTH_URL} to get their API key, then use the 'authenticate' tool.`
+	});
+	return jsonContent({ authenticated: true });
+});
+server.registerTool("list_watches", {
+	description: "List all monitored websites. Returns each watch with its UUID, URL, title, status, last checked/changed timestamps, and tags.",
+	inputSchema: z.object({ tag: z.string().optional().describe("Filter by tag UUID") })
+}, async ({ tag }) => {
+	const query = {};
+	if (tag) query.tag = tag;
+	return jsonContent(await api("/watch", { query }));
+});
+server.registerTool("create_watch", {
+	description: "Start monitoring a URL for changes. Returns the UUID of the new watch.",
+	inputSchema: z.object({
+		url: z.string().describe("URL to monitor for changes"),
+		title: z.string().optional().describe("Human-readable name for this monitor"),
+		tag: z.string().optional().describe("Tag UUID to categorize this watch"),
+		check_hours: z.number().optional().describe("Hours between checks (default: uses account setting)"),
+		check_minutes: z.number().optional().describe("Minutes between checks"),
+		fetch_backend: z.enum(["html_requests", "html_webdriver"]).optional().describe("How to fetch the page: html_requests (fast, no JS) or html_webdriver (browser with JS)")
+	})
+}, async ({ url, title, tag, check_hours, check_minutes, fetch_backend }) => {
+	const body = { url };
+	if (title) body.title = title;
+	if (tag) body.tag = tag;
+	if (fetch_backend) body.fetch_backend = fetch_backend;
+	if (check_hours !== void 0 || check_minutes !== void 0) {
+		body.time_between_check = {
+			...check_hours !== void 0 ? { hours: check_hours } : {},
+			...check_minutes !== void 0 ? { minutes: check_minutes } : {}
+		};
+		body.time_between_check_use_default = false;
+	}
+	return jsonContent(await api("/watch", {
+		method: "POST",
+		body
+	}));
+});
+server.registerTool("get_watch", {
+	description: "Get full details of a specific watch including its configuration, last check status, and change history summary.",
+	inputSchema: z.object({ uuid: z.string().describe("Watch UUID") })
+}, async ({ uuid }) => {
+	return jsonContent(await api(`/watch/${uuid}`));
+});
+server.registerTool("update_watch", {
+	description: "Update a watch's configuration. Use this to pause/resume, change check interval, update title, or modify notification settings.",
+	inputSchema: z.object({
+		uuid: z.string().describe("Watch UUID"),
+		title: z.string().optional().describe("New title"),
+		paused: z.boolean().optional().describe("Pause or resume monitoring"),
+		notification_muted: z.boolean().optional().describe("Mute or unmute notifications"),
+		tag: z.string().optional().describe("Tag UUID"),
+		check_hours: z.number().optional().describe("Hours between checks"),
+		check_minutes: z.number().optional().describe("Minutes between checks"),
+		url: z.string().optional().describe("New URL to monitor")
+	})
+}, async ({ uuid, title, paused, notification_muted, tag, check_hours, check_minutes, url }) => {
+	const body = {};
+	if (title !== void 0) body.title = title;
+	if (paused !== void 0) body.paused = paused;
+	if (notification_muted !== void 0) body.notification_muted = notification_muted;
+	if (tag !== void 0) body.tag = tag;
+	if (url !== void 0) body.url = url;
+	if (check_hours !== void 0 || check_minutes !== void 0) {
+		body.time_between_check = {
+			...check_hours !== void 0 ? { hours: check_hours } : {},
+			...check_minutes !== void 0 ? { minutes: check_minutes } : {}
+		};
+		body.time_between_check_use_default = false;
+	}
+	return jsonContent(await api(`/watch/${uuid}`, {
+		method: "PUT",
+		body
+	}));
+});
+server.registerTool("delete_watch", {
+	description: "Stop monitoring a URL and delete the watch with all its history.",
+	annotations: { destructiveHint: true },
+	inputSchema: z.object({ uuid: z.string().describe("Watch UUID to delete") })
+}, async ({ uuid }) => {
+	return jsonContent(await api(`/watch/${uuid}`, { method: "DELETE" }));
+});
+server.registerTool("get_change_history", {
+	description: "Get the list of timestamps when changes were detected for a watch. Use these timestamps with get_snapshot or get_diff.",
+	inputSchema: z.object({ uuid: z.string().describe("Watch UUID") })
+}, async ({ uuid }) => {
+	return jsonContent(await api(`/watch/${uuid}/history`));
+});
+server.registerTool("get_snapshot", {
+	description: "Get the page content captured at a specific timestamp. Use get_change_history first to find valid timestamps.",
+	inputSchema: z.object({
+		uuid: z.string().describe("Watch UUID"),
+		timestamp: z.string().describe("Timestamp from change history")
+	})
+}, async ({ uuid, timestamp }) => {
+	return jsonContent(await api(`/watch/${uuid}/history/${timestamp}`));
+});
+server.registerTool("get_diff", {
+	description: "Compare page content between two timestamps to see exactly what changed. Use get_change_history to find valid timestamps.",
+	inputSchema: z.object({
+		uuid: z.string().describe("Watch UUID"),
+		from_timestamp: z.string().describe("Earlier timestamp"),
+		to_timestamp: z.string().describe("Later timestamp")
+	})
+}, async ({ uuid, from_timestamp, to_timestamp }) => {
+	return jsonContent(await api(`/watch/${uuid}/difference/${from_timestamp}/${to_timestamp}`));
+});
+server.registerTool("search_watches", {
+	description: "Search across all watches by URL, title, or content. Returns matching watches.",
+	inputSchema: z.object({ query: z.string().describe("Search query (matches against URL, title)") })
+}, async ({ query }) => {
+	return jsonContent(await api("/search", { query: { q: query } }));
+});
+server.registerTool("list_tags", {
+	description: "List all available tags/categories for organizing watches.",
+	inputSchema: z.object({})
+}, async () => {
+	return jsonContent(await api("/tags"));
+});
+server.registerTool("trigger_recheck", {
+	description: "Force an immediate recheck of all watches (or filtered by tag). Useful when you need fresh data now rather than waiting for the next scheduled check.",
+	inputSchema: z.object({ tag: z.string().optional().describe("Only recheck watches with this tag UUID") })
+}, async ({ tag }) => {
+	const query = { recheck_all: "1" };
+	if (tag) query.tag = tag;
+	return jsonContent(await api("/watch", { query }));
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@site-spy/mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Site Spy — lets AI agents monitor websites for changes",
+  "type": "module",
+  "license": "ISC",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "site-spy",
+    "website-monitoring",
+    "ai-agents"
+  ],
+  "bin": {
+    "site-spy-mcp": "dist/index.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --banner.js '#!/usr/bin/env node'",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@site-spy/tsconfig": "workspace:*",
+    "@types/node": "^25.3.0",
+    "tsdown": "^0.20.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}