@digitalocean/mcp 0.0.7

package/README.md

@@ -0,0 +1,153 @@
+# DigitalOcean MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that provides tools to interact with DigitalOcean's [App Platform](https://www.digitalocean.com/products/app-platform) services.
+
+## Overview
+
+This MCP server exposes DigitalOcean App Platform functionality through standardized tools that can be used by any MCP client, including Claude Desktop and [Cursor](https://docs.cursor.com/context/model-context-protocol). It enables AI assistants to directly manage your DigitalOcean apps without needing to write code or remember complex API endpoints.
+
+## Features
+
+- Manage apps (create, update, delete, restart)
+- Work with deployments (list, create, get, cancel)
+- Access logs for apps and deployments
+- Retrieve execution URLs for components
+- View instance sizes and regions
+- Validate app specifications
+- Manage app alerts
+- Handle app rollbacks
+- View bandwidth metrics
+
+## Setting up with Claude Desktop
+
+1. Open Claude Desktop
+2. Go to Settings → Developer → Edit Config
+3. This will open `claude_desktop_config.json`
+4. Add or update the configuration with:
+
+```json
+{
+  "mcpServers": {
+    "digitalocean": {
+      "command": "npx",
+      "args": ["@digitalocean/mcp"],
+      "env": {
+        "DIGITALOCEAN_API_TOKEN": "your_personal_access_token"
+      }
+    }
+  }
+}
+```
+
+5. Replace `your_personal_access_token` with your actual DigitalOcean API token
+6. Save the file and restart Claude Desktop
+
+## Setting up with Cursor
+
+1. Go to Cursor Settings → MCP → Click on "Add a new global MCP server"
+2. This will open `~/.cursor/mcp.json`
+3. Add or update the configuration with the same JSON as used for Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "digitalocean": {
+      "command": "npx",
+      "args": ["@digitalocean/mcp"],
+      "env": {
+        "DIGITALOCEAN_API_TOKEN": "your_personal_access_token"
+      }
+    }
+  }
+}
+```
+
+4. Replace `your_personal_access_token` with your actual DigitalOcean API token
+5. Save the file and ensure the server is activated in Cursor Settings → MCP
+
+## Using with Claude Desktop or Cursor
+
+Once configured, you can start chatting with the AI assistant using natural language to manage your DigitalOcean App Platform resources. Here are some examples of what you can ask:
+
+### Basic App Management
+
+- "How many DigitalOcean apps do I have?"
+- "List all my current apps on DigitalOcean"
+- "Show me details for my app called 'customer-portal'"
+- "Restart my app 'api-backend'"
+- "Delete the app named 'test-environment'"
+
+### Deployments
+
+- "When was the last deployment for my 'production-website' app?"
+- "Show me all deployments for my 'user-service' app"
+- "Cancel the current deployment for my 'staging-env' app"
+- "What's the status of the latest deployment for my 'data-processor' app?"
+
+### Creating and Updating Apps
+
+- "Create a new static site app on DigitalOcean that deploys from my GitHub repo yourusername/static-website"
+- "Create a Flask app on DigitalOcean with the following specification: Python 3.9, 1 CPU, 1GB RAM, connected to my GitHub repo yourusername/flask-app"
+- "Update my 'api-service' app to use 2GB of RAM instead of 1GB"
+- "Set up a Node.js app that uses a managed PostgreSQL database"
+
+### Logs and Debugging
+
+- "Show me the logs for the 'web' component of my 'ecommerce' app"
+- "Get the latest build logs for my 'backend-api' app"
+- "What errors are showing up in my 'auth-service' deployment logs?"
+
+### Infrastructure Information
+
+- "What regions can I deploy my DigitalOcean apps to?"
+- "List all available instance sizes for app components"
+- "What's the smallest instance size I can use for a service component?"
+- "Show me my bandwidth usage across all apps this month"
+
+## Available Tools
+
+Here's a quick overview of the available tools:
+
+- `list_apps` - List all apps on your account
+- `create_app` - Create a new app with an app specification
+- `get_app` - Get details about a specific app
+- `update_app` - Update an existing app
+- `delete_app` - Delete an app
+- `restart_app` - Restart an app
+- `list_deployments` - List all deployments for an app
+- `create_deployment` - Create a new deployment
+- `get_deployment` - Get details about a specific deployment
+- `cancel_deployment` - Cancel a deployment
+- `retrieve_active_deployment_logs` - Get logs for a component of the active deployment
+- `download_logs` - Download logs from a URL
+- `list_app_regions` - List all regions supported by App Platform
+- `list_instance_sizes` - List all instance sizes for components
+- `validate_app_spec` - Validate an app specification
+- `list_app_alerts` - List alerts for an app
+- `update_app_alert_destinations` - Update alert destinations
+- `rollback_app` - Rollback an app to a previous deployment
+- `validate_app_rollback` - Validate an app rollback
+- `commit_app_rollback` - Commit an app rollback
+- `revert_app_rollback` - Revert an app rollback
+- `get_app_bandwidth_daily_metrics` - Get bandwidth metrics for an app
+- `get_all_app_bandwidth_daily_metrics` - Get bandwidth metrics for all apps
+
+## Troubleshooting
+
+### Common Issues
+
+- **Authentication Problems**: Ensure your DigitalOcean API token is valid and has the necessary permissions
+
+### If Tools Are Not Showing Up
+
+1. Check that the MCP server icon appears in the UI
+2. Verify your API token has the necessary permissions
+3. Check the app logs for any error messages
+
+## License
+
+[MIT License](LICENSE)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/build/DOMcpServer.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOMcpServer = void 0;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+class DOMcpServer extends mcp_js_1.McpServer {
+    constructor(options) {
+        super(options);
+    }
+    registerTool({ name, description, parameters, cb, }) {
+        if (parameters) {
+            this.tool(name, description, parameters, cb);
+        }
+        else {
+            this.tool(name, description, cb);
+        }
+    }
+}
+exports.DOMcpServer = DOMcpServer;

package/build/api.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DigitalOceanApiError = void 0;
+exports.createClient = createClient;
+const digitalocean_openapi_yaml_zod_1 = require("./specs/digitalocean-openapi.yaml.zod");
+const logger_1 = __importDefault(require("./logger"));
+const BASE_URL = "https://api.digitalocean.com";
+function getToken() {
+    const token = process.env.DIGITALOCEAN_API_TOKEN;
+    if (!token) {
+        throw new Error("DIGITALOCEAN_API_TOKEN is not set");
+    }
+    return token;
+}
+function parsePath(path, pathParams = {}) {
+    // extract the path params from the path. Each params will be in the form {param_name}
+    const pathParts = path.split("/");
+    const newParts = pathParts.map((part) => {
+        if (part.startsWith("{") && part.endsWith("}")) {
+            const key = part.slice(1, -1);
+            return pathParams[key] || part;
+        }
+        return part;
+    });
+    return newParts.join("/");
+}
+function createClient(params = {}) {
+    const token = getToken();
+    const sharedHeaders = {
+        "User-Agent": "ModelContext/0.1.0",
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    const client = (0, digitalocean_openapi_yaml_zod_1.createApiClient)(async (method, url, params) => {
+        const queryString = new URLSearchParams(params?.query).toString();
+        const _headers = {
+            ...sharedHeaders,
+            ...params?.header,
+        };
+        const _url = parsePath(url, params?.path);
+        const urlWithQuery = queryString ? `${_url}?${queryString}` : _url;
+        const body = params?.body && !["GET", "HEAD"].includes(method)
+            ? JSON.stringify(params?.body)
+            : undefined;
+        const res = await fetch(urlWithQuery, {
+            method,
+            headers: _headers,
+            body,
+        });
+        if (res.status !== 200) {
+            const errorObj = (await res.json());
+            if (errorObj.id) {
+                const error = DigitalOceanApiError.fromResponse(errorObj);
+                logger_1.default.error(`API Error: ${method.toUpperCase()} ${urlWithQuery} ${error.message}`);
+                throw error;
+            }
+            throw new Error(`${res.status} ${res.statusText}`);
+        }
+        const responseContentType = res.headers.get("content-type");
+        if (responseContentType?.includes("application/json")) {
+            return res.json();
+        }
+        else if (responseContentType?.includes("text/")) {
+            return res.text();
+        }
+        else if (responseContentType?.includes("application/octet-stream")) {
+            return res.blob();
+        }
+        else {
+            return res.text();
+        }
+    }, BASE_URL);
+    return { client };
+}
+class DigitalOceanApiError extends Error {
+    id;
+    message;
+    static fromResponse(response) {
+        return new DigitalOceanApiError(response.id, response.message);
+    }
+    static isDigitalOceanApiError(error) {
+        return error instanceof DigitalOceanApiError;
+    }
+    constructor(id, message) {
+        super(message);
+        this.id = id;
+        this.message = message;
+    }
+}
+exports.DigitalOceanApiError = DigitalOceanApiError;

package/build/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = __importDefault(require("./logger"));
+const server_1 = require("./server");
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+async function main() {
+    const server = (0, server_1.createServer)();
+    (0, server_1.startStdioServer)(server);
+}
+main().catch((error) => {
+    logger_1.default.error("Error starting server:", error);
+    process.exit(1);
+});

package/build/logger.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function toMessage(...args) {
+    return args
+        .map((arg) => (typeof arg === "object" ? JSON.stringify(arg) : String(arg)))
+        .join(" ");
+}
+const logger = {
+    info: (...args) => {
+        const entry = {
+            level: "info",
+            message: toMessage(...args),
+            timestamp: new Date().toISOString(),
+        };
+        process.stdout.write(`${JSON.stringify(entry)}\n`);
+    },
+    error: (...args) => {
+        const entry = {
+            level: "error",
+            message: toMessage(...args),
+            timestamp: new Date().toISOString(),
+        };
+        process.stderr.write(`${JSON.stringify(entry)}\n`);
+    },
+    warn: (...args) => {
+        const entry = {
+            level: "warn",
+            message: toMessage(...args),
+            timestamp: new Date().toISOString(),
+        };
+        process.stderr.write(`${JSON.stringify(entry)}\n`);
+    },
+    debug: (...args) => {
+        const entry = {
+            level: "debug",
+            message: toMessage(...args),
+            timestamp: new Date().toISOString(),
+        };
+        process.stdout.write(`${JSON.stringify(entry)}\n`);
+    },
+};
+exports.default = logger;

package/build/server.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+exports.startStdioServer = startStdioServer;
+const app_1 = require("./tools/app");
+const DOMcpServer_1 = require("./DOMcpServer");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const logger_1 = __importDefault(require("./logger"));
+const package_json_1 = __importDefault(require("../package.json"));
+function createServer() {
+    const server = new DOMcpServer_1.DOMcpServer({
+        name: "DigitalOcean MCP Server",
+        version: package_json_1.default.version,
+    });
+    (0, app_1.registerAppTools)(server);
+    return server;
+}
+function startStdioServer(server) {
+    const transport = new stdio_js_1.StdioServerTransport();
+    return server.connect(transport).then(() => {
+        logger_1.default.info(`DigitalOcean MCP Server v${package_json_1.default.version} started`);
+    });
+}