bunnycdn-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvme
+
+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,294 @@
+# bunnycdn-mcp
+
+MCP server for [BunnyCDN](https://bunny.net) — manage pull zones, DNS, storage, video streaming, edge scripting, security, and Magic Containers right from your AI assistant.
+
+## Features
+
+| Tool | Description | Data Source |
+|------|-------------|-------------|
+| `bunny_get_account` | Get account details and balance | bunny.net API |
+| `bunny_get_billing_summary` | Get billing summary with charges | bunny.net API |
+| `bunny_get_statistics` | Get CDN statistics (bandwidth, requests, cache hit rate) | bunny.net API |
+| `bunny_global_search` | Search across all resources | bunny.net API |
+| `bunny_purge_url` | Purge a URL from CDN cache | bunny.net API |
+| `bunny_list_regions` | List CDN edge regions | bunny.net API |
+| `bunny_list_countries` | List countries for geo-blocking | bunny.net API |
+| `bunny_list_pull_zones` | List pull zones with search and pagination | bunny.net API |
+| `bunny_get_pull_zone` | Get pull zone details | bunny.net API |
+| `bunny_create_pull_zone` | Create a pull zone | bunny.net API |
+| `bunny_update_pull_zone` | Update pull zone settings | bunny.net API |
+| `bunny_delete_pull_zone` | Delete a pull zone | bunny.net API |
+| `bunny_purge_pull_zone_cache` | Purge entire pull zone cache | bunny.net API |
+| `bunny_manage_pull_zone_hostnames` | Add or remove custom hostnames | bunny.net API |
+| `bunny_manage_edge_rules` | Add, update, delete, or toggle edge rules | bunny.net API |
+| `bunny_list_dns_zones` | List DNS zones | bunny.net API |
+| `bunny_get_dns_zone` | Get DNS zone with all records | bunny.net API |
+| `bunny_create_dns_zone` | Create a DNS zone | bunny.net API |
+| `bunny_update_dns_zone` | Update DNS zone settings | bunny.net API |
+| `bunny_delete_dns_zone` | Delete a DNS zone | bunny.net API |
+| `bunny_manage_dns_record` | Add, update, or delete DNS records | bunny.net API |
+| `bunny_get_dns_statistics` | Get DNS query statistics | bunny.net API |
+| `bunny_list_storage_zones` | List storage zones | bunny.net API |
+| `bunny_get_storage_zone` | Get storage zone details | bunny.net API |
+| `bunny_create_storage_zone` | Create a storage zone | bunny.net API |
+| `bunny_get_storage_zone_statistics` | Get storage zone usage statistics | bunny.net API |
+| `bunny_list_storage_files` | List files and directories | Storage API |
+| `bunny_download_storage_file` | Download file content | Storage API |
+| `bunny_delete_storage_file` | Delete a file or directory | Storage API |
+| `bunny_list_video_libraries` | List video libraries | bunny.net API |
+| `bunny_get_video_library` | Get library details | bunny.net API |
+| `bunny_create_video_library` | Create a video library | bunny.net API |
+| `bunny_update_video_library` | Update library settings | bunny.net API |
+| `bunny_list_videos` | List videos with search and pagination | Stream API |
+| `bunny_get_video` | Get video details | Stream API |
+| `bunny_create_video` | Create video object, optionally fetch from URL | Stream API |
+| `bunny_update_video` | Update video metadata | Stream API |
+| `bunny_delete_video` | Delete a video | Stream API |
+| `bunny_get_video_statistics` | Get view statistics | Stream API |
+| `bunny_get_video_heatmap` | Get attention heatmap data | Stream API |
+| `bunny_reencode_video` | Re-encode a video | Stream API |
+| `bunny_list_collections` | List video collections | Stream API |
+| `bunny_get_collection` | Get collection details | Stream API |
+| `bunny_manage_collection` | Create, update, or delete collections | Stream API |
+| `bunny_list_edge_scripts` | List edge scripts | bunny.net API |
+| `bunny_get_edge_script` | Get script details | bunny.net API |
+| `bunny_get_edge_script_code` | Get script source code | bunny.net API |
+| `bunny_set_edge_script_code` | Upload script code (saved as draft) | bunny.net API |
+| `bunny_manage_edge_script` | Create, update, or delete scripts | bunny.net API |
+| `bunny_publish_edge_script` | Publish a release to edge servers | bunny.net API |
+| `bunny_manage_edge_script_variables` | Manage environment variables and secrets | bunny.net API |
+| `bunny_list_shield_zones` | List shield security zones | bunny.net API |
+| `bunny_get_shield_zone` | Get zone by shield zone ID or pull zone ID | bunny.net API |
+| `bunny_get_waf_rules` | Get WAF rules and profiles | bunny.net API |
+| `bunny_manage_waf_custom_rule` | Create, update, or delete custom WAF rules | bunny.net API |
+| `bunny_list_rate_limit_rules` | List rate limiting rules | bunny.net API |
+| `bunny_manage_rate_limit_rule` | Create, update, or delete rate limit rules | bunny.net API |
+| `bunny_get_shield_metrics` | Get security metrics overview | bunny.net API |
+| `bunny_get_bot_detection` | Get or update bot detection settings | bunny.net API |
+| `bunny_list_mc_apps` | List Magic Container applications | bunny.net API |
+| `bunny_get_mc_app` | Get application details | bunny.net API |
+| `bunny_get_mc_app_overview` | Get app overview with real-time metrics | bunny.net API |
+| `bunny_manage_mc_app` | Create, update, or delete applications | bunny.net API |
+| `bunny_mc_app_lifecycle` | Deploy, undeploy, or restart applications | bunny.net API |
+| `bunny_list_mc_registries` | List container registries | bunny.net API |
+| `bunny_list_mc_regions` | List deployment regions | bunny.net API |
+| `bunny_get_mc_app_statistics` | Get application statistics | bunny.net API |
+| `bunny_get_origin_errors` | Get origin error logs for a pull zone | bunny.net API |
+
+**Data sources:** Tools marked **Storage API** require `BUNNY_STORAGE_KEY`. Tools marked **Stream API** require `BUNNY_STREAM_KEY`. All other tools use `BUNNY_API_KEY`.
+
+## Prerequisites
+
+- Node.js >= 18
+- A [bunny.net](https://bunny.net) account with an API key
+- Optional: Stream library API key (for video tools)
+- Optional: Storage zone password (for file tools)
+
+## Setup
+
+No installation needed — just configure your MCP client:
+
+<details>
+<summary>VS Code / Copilot</summary>
+
+Add to `.vscode/mcp.json`:
+```json
+{
+  "servers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add --transport stdio bunnycdn -- npx -y bunnycdn-mcp
+```
+
+Or add to `.mcp.json` (shared with team):
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Zed</summary>
+
+Add to `settings.json`:
+```json
+{
+  "context_servers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>JetBrains IDEs</summary>
+
+Open **Settings → Tools → AI Assistant → MCP**, click **+**, and paste:
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+```bash
+gemini mcp add bunnycdn -- npx -y bunnycdn-mcp
+```
+
+Or add to `~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "bunnycdn": {
+      "command": "npx",
+      "args": ["-y", "bunnycdn-mcp"],
+      "env": {
+        "BUNNY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Other MCP clients</summary>
+
+Any MCP client that supports **stdio** transport can use this server. The command is:
+```
+npx -y bunnycdn-mcp
+```
+See the [full list of MCP clients](https://modelcontextprotocol.io/clients).
+</details>
+
+### Optional environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `BUNNY_STREAM_KEY` | Video library API key — enables Stream video and collection tools |
+| `BUNNY_STORAGE_KEY` | Storage zone password — enables Storage file tools |
+| `BUNNY_STORAGE_REGION` | Storage region code (default: empty for Falkenstein) |
+| `BUNNY_STORAGE_ZONE` | Default storage zone name |
+
+Add these to the `env` block in your MCP client configuration above.
+
+### Local development
+
+```bash
+git clone https://github.com/anvme/bunnycdn-mcp.git
+cd bunnycdn-mcp
+npm install
+npm test
+node index.js
+```
+
+## How It Works
+
+This MCP server connects to the [bunny.net API](https://docs.bunny.net/reference/bunnynet-api-overview) using your API key. It registers up to 68 tools depending on which API keys are provided:
+
+- **Core tools** (55 tools) — always available with `BUNNY_API_KEY`
+- **Stream tools** (11 tools) — registered when `BUNNY_STREAM_KEY` is set
+- **Storage file tools** (3 tools) — registered when `BUNNY_STORAGE_KEY` is set
+
+All read operations are cached in-memory with a short TTL for performance. Every tool includes MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can make informed decisions about tool approval.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import axios from "axios";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { createCache } from "./lib/helpers.js";
+import { registerAccountTools } from "./lib/tools/account.js";
+import { registerPullZoneTools } from "./lib/tools/pull-zones.js";
+import { registerDnsTools } from "./lib/tools/dns-zones.js";
+import { registerStorageZoneTools } from "./lib/tools/storage-zones.js";
+import { registerStorageFileTools } from "./lib/tools/storage-files.js";
+import { registerStreamLibraryTools } from "./lib/tools/stream-libraries.js";
+import { registerStreamVideoTools } from "./lib/tools/stream-videos.js";
+import { registerStreamCollectionTools } from "./lib/tools/stream-collections.js";
+import { registerEdgeScriptingTools } from "./lib/tools/edge-scripting.js";
+import { registerShieldTools } from "./lib/tools/shield.js";
+import { registerMagicContainerTools } from "./lib/tools/magic-containers.js";
+import { registerOriginErrorTools } from "./lib/tools/origin-errors.js";
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+process.on("uncaughtException", (err) => {
+  process.stderr.write(`Uncaught exception: ${err.message}\n`);
+  process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+  process.stderr.write(`Unhandled rejection: ${reason}\n`);
+  process.exit(1);
+});
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf-8"));
+
+// ─── Validate API Key ────────────────────────────────────────────────────────
+
+const BUNNY_API_KEY = process.env.BUNNY_API_KEY;
+if (!BUNNY_API_KEY) {
+  process.stderr.write("Fatal: BUNNY_API_KEY environment variable is required\n");
+  process.exit(1);
+}
+
+// ─── HTTP Clients ────────────────────────────────────────────────────────────
+
+const ua = `${pkg.name}/${pkg.version}`;
+
+const coreHttp = axios.create({
+  baseURL: "https://api.bunny.net",
+  timeout: 15_000,
+  maxContentLength: 5 * 1024 * 1024,
+  headers: { "User-Agent": ua, "AccessKey": BUNNY_API_KEY, "Accept": "application/json" },
+});
+
+const originHttp = axios.create({
+  baseURL: "https://cdn-origin-logging.bunny.net",
+  timeout: 15_000,
+  maxContentLength: 5 * 1024 * 1024,
+  headers: { "User-Agent": ua, "AccessKey": BUNNY_API_KEY, "Accept": "application/json" },
+});
+
+const BUNNY_STREAM_KEY = process.env.BUNNY_STREAM_KEY;
+const streamHttp = BUNNY_STREAM_KEY ? axios.create({
+  baseURL: "https://video.bunnycdn.com",
+  timeout: 15_000,
+  maxContentLength: 5 * 1024 * 1024,
+  headers: { "User-Agent": ua, "AccessKey": BUNNY_STREAM_KEY, "Accept": "application/json" },
+}) : null;
+
+const BUNNY_STORAGE_KEY = process.env.BUNNY_STORAGE_KEY;
+const storageRegion = process.env.BUNNY_STORAGE_REGION || "";
+const storageBase = storageRegion
+  ? `https://${storageRegion}.storage.bunnycdn.com`
+  : "https://storage.bunnycdn.com";
+const storageHttp = BUNNY_STORAGE_KEY ? axios.create({
+  baseURL: storageBase,
+  timeout: 30_000,
+  maxContentLength: 10 * 1024 * 1024,
+  headers: { "User-Agent": ua, "AccessKey": BUNNY_STORAGE_KEY, "Accept": "*/*" },
+}) : null;
+
+// ─── Cache ───────────────────────────────────────────────────────────────────
+
+const cache = createCache({ ttl: 3 * 60 * 1000, max: 300 });
+
+// ─── Server ──────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: pkg.name,
+  description: pkg.description,
+  version: pkg.version,
+});
+
+// ─── Register Tools ──────────────────────────────────────────────────────────
+
+registerAccountTools(server, coreHttp, cache);
+registerPullZoneTools(server, coreHttp, cache);
+registerDnsTools(server, coreHttp, cache);
+registerStorageZoneTools(server, coreHttp, cache);
+registerStreamLibraryTools(server, coreHttp, cache);
+registerEdgeScriptingTools(server, coreHttp, cache);
+registerShieldTools(server, coreHttp, cache);
+registerMagicContainerTools(server, coreHttp, cache);
+registerOriginErrorTools(server, originHttp, cache);
+
+if (streamHttp) {
+  registerStreamVideoTools(server, streamHttp, cache);
+  registerStreamCollectionTools(server, streamHttp, cache);
+}
+if (storageHttp) {
+  registerStorageFileTools(server, storageHttp, cache);
+}
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+try {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+} catch (err) {
+  process.stderr.write(`Fatal: failed to start server: ${err.message}\n`);
+  process.exit(1);
+}

package/lib/helpers.js

@@ -0,0 +1,87 @@
+/**
+ * Helper functions for bunnycdn-mcp server.
+ */
+
+import { z } from "zod";
+
+// ─── Cache ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_TTL = 3 * 60 * 1000;
+const MAX_ENTRIES = 300;
+
+export function createCache(opts = {}) {
+  const ttl = opts.ttl ?? DEFAULT_TTL;
+  const max = opts.max ?? MAX_ENTRIES;
+  const store = new Map();
+  return {
+    get(key) {
+      const entry = store.get(key);
+      if (!entry) return undefined;
+      if (Date.now() - entry.ts > ttl) { store.delete(key); return undefined; }
+      return entry.data;
+    },
+    set(key, data) {
+      if (store.size >= max) {
+        const oldest = store.keys().next().value;
+        store.delete(oldest);
+      }
+      store.set(key, { data, ts: Date.now() });
+    },
+    get size() { return store.size; },
+    clear() { store.clear(); },
+  };
+}
+
+// ─── Query String ──────────────────────────────────────────────────────────
+
+export function buildQueryString(params) {
+  const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== null);
+  if (entries.length === 0) return "";
+  return "?" + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+}
+
+// ─── Response Formatters ───────────────────────────────────────────────────
+
+export function formatResponse(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+export function formatError(msg) {
+  return {
+    content: [{ type: "text", text: msg }],
+    isError: true,
+  };
+}
+
+export function handleToolError(err) {
+  if (err.response) {
+    const body = err.response.data;
+    const detail = body?.Message ?? body?.ErrorKey ?? "";
+    return formatError(`BunnyCDN API error: ${err.response.status}${detail ? ` — ${detail}` : ""}`);
+  }
+  return formatError(`Network error: ${err.message}`);
+}
+
+// ─── Reusable Zod Parameters ───────────────────────────────────────────────
+
+export function pageParam() {
+  return z.number().min(1).optional().describe("Page number. Default: 1");
+}
+
+export function perPageParam() {
+  return z.number().min(1).max(1000).optional().describe("Items per page. Default: 1000");
+}
+
+export function dateFromParam() {
+  return z.string().optional().describe("Start date (YYYY-MM-DD or ISO 8601)");
+}
+
+export function dateToParam() {
+  return z.string().optional().describe("End date (YYYY-MM-DD or ISO 8601)");
+}
+
+export function idParam(label) {
+  return z.number().int().positive().describe(`${label} ID`);
+}