@dokploy/mcp 0.0.1

package/build/handler.js

@@ -0,0 +1,29 @@
+import apiClient from "./utils/apiClient.js";
+import { createLogger } from "./utils/logger.js";
+import { ResponseFormatter } from "./utils/responseFormatter.js";
+const logger = createLogger("ToolHandler");
+export function createHandler(tool) {
+    return async (input) => {
+        try {
+            logger.info(`Executing tool: ${tool.name}`, { input });
+            const response = tool.method === "GET"
+                ? await apiClient.get(tool.path, { params: input })
+                : await apiClient.post(tool.path, input);
+            return ResponseFormatter.success(`${tool.name} completed successfully`, response.data);
+        }
+        catch (error) {
+            logger.error(`Tool execution failed: ${tool.name}`, {
+                error: error instanceof Error ? error.message : "Unknown error",
+            });
+            if (error instanceof Error) {
+                if (error.message.includes("401") || error.message.includes("Unauthorized")) {
+                    return ResponseFormatter.error(`Authentication failed for ${tool.name}`, "Please check your DOKPLOY_API_KEY configuration");
+                }
+                if (error.message.includes("404") || error.message.includes("Not Found")) {
+                    return ResponseFormatter.error("Resource not found", `The requested resource for ${tool.name} could not be found`);
+                }
+            }
+            return ResponseFormatter.error(`Failed to execute ${tool.name}`, `Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    };
+}

package/build/http-server.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { serve } from "@hono/node-server";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { Hono } from "hono";
+import { createServer } from "./server.js";
+import { createLogger } from "./utils/logger.js";
+const PORT = 3000;
+const logger = createLogger("MCP-HTTP-Server");
+const jsonrpcError = (code, message) => ({
+    jsonrpc: "2.0",
+    error: { code, message },
+    id: null,
+});
+// When MCP transport takes over the raw Node response, we must prevent
+// Hono/@hono/node-server from trying to write its own response headers.
+// We return a Promise that NEVER resolves — the underlying Node response
+// is already being handled by the MCP transport, so Hono must not touch it.
+function neverResolve() {
+    return new Promise(() => { });
+}
+export async function main() {
+    const app = new Hono();
+    const transports = {
+        streamable: {},
+        sse: {},
+    };
+    // Health check
+    app.get("/health", (c) => c.json({ status: "ok", timestamp: new Date().toISOString() }));
+    // Modern Streamable HTTP - POST
+    app.post("/mcp", async (c) => {
+        const { incoming, outgoing } = c.env;
+        try {
+            const sessionId = c.req.header("mcp-session-id");
+            let transport;
+            const body = await c.req.json();
+            if (sessionId && transports.streamable[sessionId]) {
+                transport = transports.streamable[sessionId];
+            }
+            else if (!sessionId && isInitializeRequest(body)) {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        transports.streamable[sid] = transport;
+                        logger.info("New MCP session initialized", { sessionId: sid });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId) {
+                        logger.info("MCP session closed", { sessionId: transport.sessionId });
+                        delete transports.streamable[transport.sessionId];
+                    }
+                };
+                const server = createServer();
+                await server.connect(transport);
+            }
+            else {
+                return c.json(jsonrpcError(-32000, "Bad Request: No valid session ID or invalid initialization request"), 400);
+            }
+            await transport.handleRequest(incoming, outgoing, body);
+            return neverResolve();
+        }
+        catch (error) {
+            logger.error("Error handling HTTP request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return c.json(jsonrpcError(-32603, "Internal server error"), 500);
+        }
+    });
+    // Modern Streamable HTTP - GET (SSE notifications)
+    app.get("/mcp", async (c) => {
+        const { incoming, outgoing } = c.env;
+        const sessionId = c.req.header("mcp-session-id");
+        if (!sessionId || !transports.streamable[sessionId]) {
+            return c.json(jsonrpcError(-32000, "Invalid or missing session ID"), 400);
+        }
+        try {
+            const transport = transports.streamable[sessionId];
+            await transport.handleRequest(incoming, outgoing);
+            return neverResolve();
+        }
+        catch (error) {
+            logger.error("Error handling GET request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return c.json(jsonrpcError(-32603, "Internal server error"), 500);
+        }
+    });
+    // Modern Streamable HTTP - DELETE (session termination)
+    app.delete("/mcp", async (c) => {
+        const { incoming, outgoing } = c.env;
+        const sessionId = c.req.header("mcp-session-id");
+        if (!sessionId || !transports.streamable[sessionId]) {
+            return c.json(jsonrpcError(-32000, "Invalid or missing session ID"), 400);
+        }
+        try {
+            const transport = transports.streamable[sessionId];
+            await transport.handleRequest(incoming, outgoing);
+            if (transports.streamable[sessionId]) {
+                logger.info("MCP session terminated", { sessionId });
+                delete transports.streamable[sessionId];
+            }
+            return neverResolve();
+        }
+        catch (error) {
+            logger.error("Error handling DELETE request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return c.json(jsonrpcError(-32603, "Internal server error"), 500);
+        }
+    });
+    // Legacy SSE endpoint
+    app.get("/sse", async (c) => {
+        const { outgoing } = c.env;
+        try {
+            const transport = new SSEServerTransport("/messages", outgoing);
+            transports.sse[transport.sessionId] = transport;
+            outgoing.on("close", () => {
+                logger.info("Legacy SSE session closed", { sessionId: transport.sessionId });
+                delete transports.sse[transport.sessionId];
+            });
+            const server = createServer();
+            await server.connect(transport);
+            logger.info("New legacy SSE session initialized", { sessionId: transport.sessionId });
+            return neverResolve();
+        }
+        catch (error) {
+            logger.error("Error handling SSE request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return c.json(jsonrpcError(-32603, "Internal server error"), 500);
+        }
+    });
+    // Legacy message endpoint
+    app.post("/messages", async (c) => {
+        const { incoming, outgoing } = c.env;
+        try {
+            const sessionId = c.req.query("sessionId");
+            if (!sessionId) {
+                return c.json(jsonrpcError(-32000, "sessionId query parameter is required"), 400);
+            }
+            const transport = transports.sse[sessionId];
+            if (!transport) {
+                return c.json(jsonrpcError(-32000, "No transport found for sessionId"), 400);
+            }
+            const body = await c.req.json();
+            await transport.handlePostMessage(incoming, outgoing, body);
+            return neverResolve();
+        }
+        catch (error) {
+            logger.error("Error handling legacy message request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return c.json(jsonrpcError(-32603, "Internal server error"), 500);
+        }
+    });
+    serve({ fetch: app.fetch, port: PORT }, () => {
+        logger.info("MCP Dokploy server started", {
+            port: PORT,
+            protocols: ["Streamable HTTP (MCP 2025-03-26)", "Legacy SSE (MCP 2024-11-05)"],
+            endpoints: {
+                modern: `http://localhost:${PORT}/mcp`,
+                legacy: `http://localhost:${PORT}/sse`,
+                health: `http://localhost:${PORT}/health`,
+            },
+        });
+    });
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((error) => {
+        logger.error("Fatal error occurred", {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        process.exit(1);
+    });
+}

package/build/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { createLogger } from "./utils/logger.js";
+const logger = createLogger("MCP-Entry");
+async function main() {
+    // Check if running in HTTP mode
+    const args = process.argv.slice(2);
+    const httpMode = args.includes("--http") ||
+        args.includes("--sse") ||
+        process.env.MCP_TRANSPORT === "http" ||
+        process.env.MCP_TRANSPORT === "sse";
+    if (httpMode) {
+        // Dynamic import to avoid loading Express dependencies when not needed
+        const httpModule = await import("./http-server.js");
+        if (typeof httpModule.main === "function") {
+            return httpModule.main();
+        }
+        else {
+            throw new Error("HTTP server module does not export main function");
+        }
+    }
+    // Default: stdio mode
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP Dokploy CLI server running via stdio");
+}
+main().catch((error) => {
+    logger.error("Fatal error occurred", {
+        error: error.message,
+        stack: error.stack,
+    });
+    process.exit(1);
+});

package/build/server.js

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { generatedTools } from "./generated/tools.js";
+import { createHandler } from "./handler.js";
+import { createLogger } from "./utils/logger.js";
+const logger = createLogger("MCP-Server");
+function getEnabledTools() {
+    const enabledTags = process.env.DOKPLOY_ENABLED_TAGS;
+    if (!enabledTags) {
+        return generatedTools;
+    }
+    const tags = new Set(enabledTags
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean));
+    const filtered = generatedTools.filter((tool) => tags.has(tool.tag.toLowerCase()));
+    logger.info("Filtered tools by tags", {
+        enabledTags: [...tags],
+        total: generatedTools.length,
+        loaded: filtered.length,
+    });
+    return filtered;
+}
+export function createServer() {
+    const server = new McpServer({
+        name: "dokploy",
+        version: "2.0.0",
+    });
+    const tools = getEnabledTools();
+    for (const tool of tools) {
+        server.tool(tool.name, tool.description, tool.schema.shape, tool.annotations ?? {}, createHandler(tool));
+    }
+    return server;
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/build/utils/apiClient.js

@@ -0,0 +1,128 @@
+import axios from "axios";
+import { getClientConfig } from "./clientConfig.js";
+import { createLogger } from "./logger.js";
+// Create logger instance for axios client
+const logger = createLogger("AxiosClient");
+// Get configuration from existing client config
+const config = getClientConfig();
+// Default headers for MCP server context
+const DEFAULT_HEADERS = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "x-api-key": config.authToken, // Use the same auth mechanism as httpClient
+};
+// Create axios instance with configuration from clientConfig
+// Ensure baseURL includes /api prefix for Dokploy API routes
+const baseURL = `${config.dokployUrl.replace(/\/+$/, "")}/api`;
+const apiClient = axios.create({
+    baseURL,
+    timeout: config.timeout,
+    headers: DEFAULT_HEADERS,
+});
+// Request interceptor - Add request timing and logging
+apiClient.interceptors.request.use((config) => {
+    // Add request timestamp for performance monitoring
+    config.metadata = { startTime: Date.now() };
+    logger.debug("Making API request", {
+        method: config.method?.toUpperCase(),
+        url: config.url,
+        baseURL: config.baseURL,
+        hasData: !!config.data,
+    });
+    return config;
+}, (error) => {
+    logger.error("Request interceptor error", { error: error.message });
+    return Promise.reject(error);
+});
+// Response interceptor - Handle responses and errors with proper logging
+apiClient.interceptors.response.use((response) => {
+    // Log response time for performance monitoring
+    const metadata = response.config.metadata;
+    const startTime = metadata?.startTime;
+    if (startTime) {
+        const duration = Date.now() - startTime;
+        logger.info("API request completed", {
+            method: response.config.method?.toUpperCase(),
+            url: response.config.url,
+            status: response.status,
+            duration: `${duration}ms`,
+        });
+    }
+    return response;
+}, (error) => {
+    const { response, request, config } = error;
+    // Handle different error scenarios with proper logging
+    if (response) {
+        // Server responded with error status
+        handleServerError(response);
+    }
+    else if (request) {
+        // Request was made but no response received
+        handleNetworkError(request, config);
+    }
+    else {
+        // Something else happened
+        handleUnknownError(error);
+    }
+    return Promise.reject(error);
+});
+// Helper Functions
+function handleServerError(response) {
+    const { status, data, config } = response;
+    const errorContext = {
+        status,
+        method: config?.method?.toUpperCase(),
+        url: config?.url,
+        message: data?.message || data?.error || "Unknown server error",
+    };
+    switch (status) {
+        case 401:
+            logger.error("Authentication failed - Invalid or expired API key", errorContext);
+            break;
+        case 403:
+            logger.error("Access forbidden - Insufficient permissions", errorContext);
+            break;
+        case 404:
+            logger.error("Resource not found", errorContext);
+            break;
+        case 422:
+            logger.error("Validation error", {
+                ...errorContext,
+                errors: data?.errors,
+            });
+            break;
+        case 500:
+            logger.error("Internal server error", errorContext);
+            break;
+        default:
+            logger.error(`Server error (${status})`, errorContext);
+    }
+}
+function handleNetworkError(_request, config) {
+    logger.error("Network error - Request failed", {
+        method: config?.method?.toUpperCase(),
+        url: config?.url || "Unknown URL",
+        timeout: config?.timeout || "No timeout set",
+        error: "No response received from server",
+    });
+}
+function handleUnknownError(error) {
+    logger.error("Unknown error occurred", {
+        error: error.message,
+        stack: error.stack,
+    });
+}
+// Utility function to update auth token (for MCP context)
+export function setAuthToken(token) {
+    // Update default headers for future requests
+    apiClient.defaults.headers.common["x-api-key"] = token;
+    logger.info("Auth token updated for API client");
+}
+// Utility function to clear auth token
+export function clearAuthToken() {
+    // Remove authorization header
+    delete apiClient.defaults.headers.common["x-api-key"];
+    logger.info("Auth token cleared from API client");
+}
+// Export the configured axios instance
+export default apiClient;

package/build/utils/clientConfig.js

@@ -0,0 +1,37 @@
+class ConfigManager {
+    static instance;
+    config = null;
+    constructor() { }
+    static getInstance() {
+        if (!ConfigManager.instance) {
+            ConfigManager.instance = new ConfigManager();
+        }
+        return ConfigManager.instance;
+    }
+    getConfig() {
+        if (!this.config) {
+            this.config = this.loadConfig();
+        }
+        return this.config;
+    }
+    loadConfig() {
+        const dokployUrl = process.env.DOKPLOY_URL;
+        const authToken = process.env.DOKPLOY_API_KEY;
+        if (!dokployUrl) {
+            throw new Error("Environment variable DOKPLOY_URL is not defined");
+        }
+        if (!authToken) {
+            throw new Error("Environment variable DOKPLOY_API_KEY is not defined");
+        }
+        return {
+            dokployUrl,
+            authToken,
+            timeout: parseInt(process.env.DOKPLOY_TIMEOUT || "30000", 10),
+            retryAttempts: parseInt(process.env.DOKPLOY_RETRY_ATTEMPTS || "3", 10),
+            retryDelay: parseInt(process.env.DOKPLOY_RETRY_DELAY || "1000", 10),
+        };
+    }
+}
+export function getClientConfig() {
+    return ConfigManager.getInstance().getConfig();
+}

package/build/utils/logger.js

@@ -0,0 +1,38 @@
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "error";
+    LogLevel["WARN"] = "warn";
+    LogLevel["INFO"] = "info";
+    LogLevel["DEBUG"] = "debug";
+})(LogLevel || (LogLevel = {}));
+class Logger {
+    context;
+    constructor(context = "MCP-Server") {
+        this.context = context;
+    }
+    log(level, message, meta) {
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            context: { service: this.context, ...meta },
+        };
+        // eslint-disable-next-line no-console
+        console.error(JSON.stringify(entry));
+    }
+    error(message, meta) {
+        this.log(LogLevel.ERROR, message, meta);
+    }
+    warn(message, meta) {
+        this.log(LogLevel.WARN, message, meta);
+    }
+    info(message, meta) {
+        this.log(LogLevel.INFO, message, meta);
+    }
+    debug(message, meta) {
+        this.log(LogLevel.DEBUG, message, meta);
+    }
+}
+export function createLogger(context) {
+    return new Logger(context);
+}

package/build/utils/responseFormatter.js

@@ -0,0 +1,33 @@
+export class ResponseFormatter {
+    static success(message, data) {
+        const responseData = {
+            success: true,
+            message,
+            ...(data && typeof data === "object" && data !== null ? { data } : {}),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(responseData, null, 2),
+                },
+            ],
+        };
+    }
+    static error(message, details) {
+        const errorData = {
+            success: false,
+            error: message,
+            ...(details && { details }),
+        };
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(errorData, null, 2),
+                },
+            ],
+        };
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@dokploy/mcp",
+  "version": "0.0.1",
+  "description": "MCP Server for Dokploy API",
+  "main": "build/index.js",
+  "bin": {
+    "dokploy-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "pnpm run clean && tsc && chmod 755 build/index.js",
+    "dev": "tsc --watch",
+    "start:stdio": "node --env-file=.env build/index.js",
+    "start:http": "node --env-file=.env build/index.js --http",
+    "start:sse": "node --env-file=.env build/index.js --sse",
+    "dev:http": "pnpm run build && pnpm run start:http",
+    "dev:sse": "pnpm run build && pnpm run start:sse",
+    "fetch-openapi": "tsx scripts/fetch-openapi.ts",
+    "generate": "tsx scripts/generate-tools.ts",
+    "generate:all": "pnpm fetch-openapi && pnpm generate",
+    "lint": "biome check",
+    "lint:fix": "biome check --fix",
+    "format": "biome format --write",
+    "format:check": "biome format",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf build",
+    "precommit": "biome check && pnpm run type-check",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dokploy/mcp.git"
+  },
+  "keywords": [
+    "modelcontextprotocol",
+    "mcp",
+    "dokploy"
+  ],
+  "author": "Henrique Andrade <developer@henriqueandrade.dev>",
+  "bugs": {
+    "url": "https://github.com/Dokploy/mcp/issues"
+  },
+  "homepage": "https://github.com/Dokploy/mcp#readme",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@hono/node-server": "^1.19.13",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.9.0",
+    "hono": "^4.12.12",
+    "zod": "^3.25.28"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22.15.21",
+    "json-schema-to-zod": "^2.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
+  }
+}