@dokploy/mcp 0.29.2 → 0.29.4

package/README.md

@@ -287,10 +287,19 @@ The configuration on Windows is slightly different compared to Linux or macOS. U
 |----------|----------|-------------|
 | `DOKPLOY_URL` | Yes | Your Dokploy server URL (e.g., `https://your-dokploy-server.com`) |
 | `DOKPLOY_API_KEY` | Yes | Your Dokploy API authentication token |
+| `DOKPLOY_CUSTOM_HEADERS` | No | JSON object of additional upstream request headers. Header names and values must be strings. Reserved headers cannot be set here: `x-api-key`, `content-type`, `accept`. |
 | `DOKPLOY_ENABLED_TAGS` | No | Comma-separated list of tags to filter which tools are loaded (e.g., `project,application,postgres`) |
 | `DOKPLOY_TIMEOUT` | No | Request timeout in milliseconds (default: `30000`) |
 | `DOKPLOY_RETRY_ATTEMPTS` | No | Number of retry attempts (default: `3`) |
 | `DOKPLOY_RETRY_DELAY` | No | Delay between retries in milliseconds (default: `1000`) |
+| `DOKPLOY_REDACT_ENV` | No | When `true`, redacts secret-bearing fields from API responses before they reach the MCP client (default: `false`). Useful when an LLM consumes responses and you don't want env vars or compose files in its context. |
+| `DOKPLOY_REDACT_FIELDS` | No | Comma-separated list of response field names to redact when `DOKPLOY_REDACT_ENV=true`. Matched case-insensitively at any nesting depth. Defaults to: `env`, `buildArgs`, `composeFile`, `dockerCompose`, `environment`, `buildSecrets`, `previewBuildSecrets`, `password`, `currentPassword`, `appPassword`, `databasePassword`, `databaseRootPassword`, `redisPassword`, `mariadbPassword`, `mongoPassword`, `mysqlPassword`, `postgresPassword`, `registryPassword`, `token`, `accessToken`, `appToken`, `apiToken`, `botToken`, `refreshToken`, `secret`, `clientSecret`, `apiKey`, `secretAccessKey`, `accessKey`, `licenseKey`, `userKey`, `privateKey`, `privateKeyPass`, `encPrivateKey`, `encPrivateKeyPass`, `sshKey`, `sshPrivateKey`, `customGitSSHKey`, `dockerAuth`. |
+
+For Dokploy instances behind Cloudflare Access or a similar reverse proxy, pass service-token headers with placeholder values like this:
+
+```bash
+DOKPLOY_CUSTOM_HEADERS='{"CF-Access-Client-Id":"your-client-id.access","CF-Access-Client-Secret":"your-client-secret"}'
+```
 
 ## Transport Modes
 

package/build/generated/tools.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED FILE — DO NOT EDIT MANUALLY
-// Generated from openapi.json on 2026-04-25
+// Generated from openapi.json on 2026-08-06
 // Run `pnpm generate` to regenerate
 import { z } from "zod";
 export const generatedTools = [
@@ -129,7 +129,7 @@ export const generatedTools = [
         tag: "application",
         method: "POST",
         path: "/application.saveGithubProvider",
-        schema: z.object({ "applicationId": z.string(), "repository": z.union([z.string(), z.null()]), "branch": z.union([z.string(), z.null()]), "owner": z.union([z.string(), z.null()]), "buildPath": z.union([z.string(), z.null()]), "githubId": z.union([z.string(), z.null()]), "triggerType": z.enum(["push", "tag"]).default("push"), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
+        schema: z.object({ "applicationId": z.string(), "repository": z.union([z.string(), z.null()]), "owner": z.union([z.string(), z.null()]), "buildPath": z.union([z.string(), z.null()]), "githubId": z.union([z.string(), z.null()]), "branch": z.string().regex(new RegExp("^[a-zA-Z0-9._\\-/]+$")).min(1), "triggerType": z.enum(["push", "tag"]).default("push"), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
         annotations: {
             title: "Application SaveGithubProvider",
             ...{ "idempotentHint": true, "openWorldHint": true },
@@ -141,7 +141,7 @@ export const generatedTools = [
         tag: "application",
         method: "POST",
         path: "/application.saveGitlabProvider",
-        schema: z.object({ "applicationId": z.string(), "gitlabBranch": z.union([z.string(), z.null()]), "gitlabBuildPath": z.union([z.string(), z.null()]), "gitlabOwner": z.union([z.string(), z.null()]), "gitlabRepository": z.union([z.string(), z.null()]), "gitlabId": z.union([z.string(), z.null()]), "gitlabProjectId": z.union([z.number(), z.null()]), "gitlabPathNamespace": z.union([z.string(), z.null()]), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
+        schema: z.object({ "applicationId": z.string(), "gitlabBuildPath": z.union([z.string(), z.null()]), "gitlabOwner": z.union([z.string(), z.null()]), "gitlabRepository": z.union([z.string(), z.null()]), "gitlabId": z.union([z.string(), z.null()]), "gitlabProjectId": z.union([z.number(), z.null()]), "gitlabPathNamespace": z.union([z.string(), z.null()]), "gitlabBranch": z.string().regex(new RegExp("^[a-zA-Z0-9._\\-/]+$")).min(1), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
         annotations: {
             title: "Application SaveGitlabProvider",
             ...{ "idempotentHint": true, "openWorldHint": true },
@@ -153,7 +153,7 @@ export const generatedTools = [
         tag: "application",
         method: "POST",
         path: "/application.saveBitbucketProvider",
-        schema: z.object({ "bitbucketBranch": z.union([z.string(), z.null()]), "bitbucketBuildPath": z.union([z.string(), z.null()]), "bitbucketOwner": z.union([z.string(), z.null()]), "bitbucketRepository": z.union([z.string(), z.null()]), "bitbucketRepositorySlug": z.union([z.string(), z.null()]), "bitbucketId": z.union([z.string(), z.null()]), "applicationId": z.string(), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
+        schema: z.object({ "bitbucketBuildPath": z.union([z.string(), z.null()]), "bitbucketOwner": z.union([z.string(), z.null()]), "bitbucketRepository": z.union([z.string(), z.null()]), "bitbucketRepositorySlug": z.union([z.string(), z.null()]), "bitbucketId": z.union([z.string(), z.null()]), "applicationId": z.string(), "bitbucketBranch": z.string().regex(new RegExp("^[a-zA-Z0-9._\\-/]+$")).min(1), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
         annotations: {
             title: "Application SaveBitbucketProvider",
             ...{ "idempotentHint": true, "openWorldHint": true },
@@ -165,7 +165,7 @@ export const generatedTools = [
         tag: "application",
         method: "POST",
         path: "/application.saveGiteaProvider",
-        schema: z.object({ "applicationId": z.string(), "giteaBranch": z.union([z.string(), z.null()]), "giteaBuildPath": z.union([z.string(), z.null()]), "giteaOwner": z.union([z.string(), z.null()]), "giteaRepository": z.union([z.string(), z.null()]), "giteaId": z.union([z.string(), z.null()]), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
+        schema: z.object({ "applicationId": z.string(), "giteaBuildPath": z.union([z.string(), z.null()]), "giteaOwner": z.union([z.string(), z.null()]), "giteaRepository": z.union([z.string(), z.null()]), "giteaId": z.union([z.string(), z.null()]), "giteaBranch": z.string().regex(new RegExp("^[a-zA-Z0-9._\\-/]+$")).min(1), "enableSubmodules": z.boolean().optional(), "watchPaths": z.union([z.array(z.string()), z.null()]).optional() }),
         annotations: {
             title: "Application SaveGiteaProvider",
             ...{ "idempotentHint": true, "openWorldHint": true },
@@ -189,7 +189,7 @@ export const generatedTools = [
         tag: "application",
         method: "POST",
         path: "/application.saveGitProvider",
-        schema: z.object({ "customGitBranch": z.union([z.string(), z.null()]), "applicationId": z.string(), "customGitBuildPath": z.union([z.string(), z.null()]), "customGitUrl": z.union([z.string(), z.null()]), "watchPaths": z.union([z.array(z.string()), z.null()]), "enableSubmodules": z.boolean().optional(), "customGitSSHKeyId": z.union([z.string(), z.null()]).optional() }),
+        schema: z.object({ "applicationId": z.string(), "customGitBuildPath": z.union([z.string(), z.null()]), "customGitUrl": z.union([z.string(), z.null()]), "watchPaths": z.union([z.array(z.string()), z.null()]), "enableSubmodules": z.boolean().optional(), "customGitBranch": z.string().regex(new RegExp("^[a-zA-Z0-9._\\-/]+$")).min(1), "customGitSSHKeyId": z.union([z.string(), z.null()]).optional() }),
         annotations: {
             title: "Application SaveGitProvider",
             ...{ "idempotentHint": true, "openWorldHint": true },
@@ -5805,7 +5805,7 @@ export const generatedTools = [
         tag: "schedule",
         method: "POST",
         path: "/schedule.create",
-        schema: z.object({ "scheduleId": z.string().optional(), "name": z.string(), "cronExpression": z.string(), "appName": z.string().optional(), "serviceName": z.union([z.string(), z.null()]).optional(), "shellType": z.enum(["bash", "sh"]).optional(), "scheduleType": z.enum(["application", "compose", "server", "dokploy-server"]).optional(), "command": z.string(), "script": z.union([z.string(), z.null()]).optional(), "applicationId": z.union([z.string(), z.null()]).optional(), "composeId": z.union([z.string(), z.null()]).optional(), "serverId": z.union([z.string(), z.null()]).optional(), "userId": z.union([z.string(), z.null()]).optional(), "enabled": z.boolean().optional(), "timezone": z.union([z.string(), z.null()]).optional(), "createdAt": z.string().optional() }),
+        schema: z.object({ "scheduleId": z.string().optional(), "name": z.string(), "description": z.union([z.string(), z.null()]).optional(), "cronExpression": z.string(), "appName": z.string().optional(), "serviceName": z.union([z.string(), z.null()]).optional(), "shellType": z.enum(["bash", "sh"]).optional(), "scheduleType": z.enum(["application", "compose", "server", "dokploy-server"]).optional(), "command": z.string(), "script": z.union([z.string(), z.null()]).optional(), "applicationId": z.union([z.string(), z.null()]).optional(), "composeId": z.union([z.string(), z.null()]).optional(), "serverId": z.union([z.string(), z.null()]).optional(), "userId": z.union([z.string(), z.null()]).optional(), "enabled": z.boolean().optional(), "timezone": z.union([z.string(), z.null()]).optional(), "createdAt": z.string().optional() }),
         annotations: {
             title: "Schedule Create",
             ...{ "openWorldHint": true },
@@ -5817,7 +5817,7 @@ export const generatedTools = [
         tag: "schedule",
         method: "POST",
         path: "/schedule.update",
-        schema: z.object({ "scheduleId": z.string().min(1), "name": z.string(), "cronExpression": z.string(), "appName": z.string().optional(), "serviceName": z.union([z.string(), z.null()]).optional(), "shellType": z.enum(["bash", "sh"]).optional(), "scheduleType": z.enum(["application", "compose", "server", "dokploy-server"]).optional(), "command": z.string(), "script": z.union([z.string(), z.null()]).optional(), "applicationId": z.union([z.string(), z.null()]).optional(), "composeId": z.union([z.string(), z.null()]).optional(), "serverId": z.union([z.string(), z.null()]).optional(), "userId": z.union([z.string(), z.null()]).optional(), "enabled": z.boolean().optional(), "timezone": z.union([z.string(), z.null()]).optional(), "createdAt": z.string().optional() }),
+        schema: z.object({ "scheduleId": z.string().min(1), "name": z.string(), "description": z.union([z.string(), z.null()]).optional(), "cronExpression": z.string(), "appName": z.string().optional(), "serviceName": z.union([z.string(), z.null()]).optional(), "shellType": z.enum(["bash", "sh"]).optional(), "scheduleType": z.enum(["application", "compose", "server", "dokploy-server"]).optional(), "command": z.string(), "script": z.union([z.string(), z.null()]).optional(), "applicationId": z.union([z.string(), z.null()]).optional(), "composeId": z.union([z.string(), z.null()]).optional(), "serverId": z.union([z.string(), z.null()]).optional(), "userId": z.union([z.string(), z.null()]).optional(), "enabled": z.boolean().optional(), "timezone": z.union([z.string(), z.null()]).optional(), "createdAt": z.string().optional() }),
         annotations: {
             title: "Schedule Update",
             ...{ "idempotentHint": true, "openWorldHint": true },

package/build/handler.js

@@ -1,15 +1,19 @@
 import apiClient from "./utils/apiClient.js";
+import { getClientConfig } from "./utils/clientConfig.js";
 import { createLogger } from "./utils/logger.js";
+import { redactSensitive } from "./utils/redactSensitive.js";
 import { ResponseFormatter } from "./utils/responseFormatter.js";
 const logger = createLogger("ToolHandler");
 export function createHandler(tool) {
     return async (input) => {
+        const { redactEnv, redactFields } = getClientConfig();
+        const redact = (value) => (redactEnv ? redactSensitive(value, redactFields) : value);
         try {
-            logger.info(`Executing tool: ${tool.name}`, { input });
+            logger.info(`Executing tool: ${tool.name}`, { input: redact(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);
+            return ResponseFormatter.success(`${tool.name} completed successfully`, redact(response.data));
         }
         catch (error) {
             logger.error(`Tool execution failed: ${tool.name}`, {

package/build/server.js

@@ -1,8 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
 import { generatedTools } from "./generated/tools.js";
 import { createHandler } from "./handler.js";
 import { createLogger } from "./utils/logger.js";
 const logger = createLogger("MCP-Server");
+const JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema";
 function getEnabledTools() {
     const enabledTags = process.env.DOKPLOY_ENABLED_TAGS;
     if (!enabledTags) {
@@ -20,6 +23,38 @@ function getEnabledTools() {
     });
     return filtered;
 }
+function stripNestedSchemaKeys(value) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            stripNestedSchemaKeys(item);
+        return;
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key === "$schema") {
+            delete record[key];
+        }
+        else {
+            stripNestedSchemaKeys(record[key]);
+        }
+    }
+}
+// Claude's API requires JSON Schema draft 2020-12. The MCP SDK's built-in
+// Zod→JSON Schema converter emits draft-07 by default, which causes a 400
+// error on tools/list. We bypass the SDK's auto-generated handler by
+// registering our own with pre-converted draft-2020-12 schemas.
+// See https://github.com/Dokploy/mcp/issues/32
+function toDraft2020_12JsonSchema(schema) {
+    const result = zodToJsonSchema(schema, {
+        target: "jsonSchema2019-09",
+        strictUnions: true,
+    });
+    stripNestedSchemaKeys(result);
+    result.$schema = JSON_SCHEMA_2020_12;
+    return result;
+}
 export function createServer() {
     const server = new McpServer({
         name: "dokploy",
@@ -29,5 +64,14 @@ export function createServer() {
     for (const tool of tools) {
         server.tool(tool.name, tool.description, tool.schema.shape, tool.annotations ?? {}, createHandler(tool));
     }
+    const toolList = tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: toDraft2020_12JsonSchema(tool.schema),
+        annotations: tool.annotations,
+    }));
+    server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: toolList,
+    }));
     return server;
 }

package/build/utils/apiClient.js

@@ -9,7 +9,8 @@ const config = getClientConfig();
 const DEFAULT_HEADERS = {
     "Content-Type": "application/json",
     Accept: "application/json",
-    "x-api-key": config.authToken, // Use the same auth mechanism as httpClient
+    ...config.customHeaders,
+    "x-api-key": config.authToken,
 };
 // Create axios instance with configuration from clientConfig
 // Ensure baseURL includes /api prefix for Dokploy API routes

package/build/utils/clientConfig.js

@@ -1,3 +1,34 @@
+import { DEFAULT_REDACTED_FIELDS } from "./redactSensitive.js";
+const RESERVED_CUSTOM_HEADER_NAMES = new Set(["x-api-key", "content-type", "accept"]);
+export function parseCustomHeaders(rawHeaders) {
+    if (rawHeaders === undefined) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawHeaders);
+    }
+    catch (error) {
+        throw new Error("Environment variable DOKPLOY_CUSTOM_HEADERS must be valid JSON containing an object of string header names to string values", { cause: error });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Environment variable DOKPLOY_CUSTOM_HEADERS must be a JSON object of string header names to string values");
+    }
+    const customHeaders = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (name.trim() === "") {
+            throw new Error("Environment variable DOKPLOY_CUSTOM_HEADERS contains an empty header name");
+        }
+        if (RESERVED_CUSTOM_HEADER_NAMES.has(name.toLowerCase())) {
+            throw new Error("Environment variable DOKPLOY_CUSTOM_HEADERS cannot override reserved headers x-api-key, content-type, or accept; configure Dokploy authentication with DOKPLOY_API_KEY");
+        }
+        if (typeof value !== "string") {
+            throw new Error("Environment variable DOKPLOY_CUSTOM_HEADERS must contain only string header values");
+        }
+        customHeaders[name] = value;
+    }
+    return customHeaders;
+}
 class ConfigManager {
     static instance;
     config = null;
@@ -23,15 +54,33 @@ class ConfigManager {
         if (!authToken) {
             throw new Error("Environment variable DOKPLOY_API_KEY is not defined");
         }
+        const redactEnv = parseBoolean(process.env.DOKPLOY_REDACT_ENV, false);
+        const parsedFields = process.env.DOKPLOY_REDACT_FIELDS?.split(",")
+            .map((f) => f.trim())
+            .filter((f) => f.length > 0) ?? [];
+        const redactFields = parsedFields.length > 0 ? parsedFields : DEFAULT_REDACTED_FIELDS;
         return {
             dokployUrl,
             authToken,
+            customHeaders: parseCustomHeaders(process.env.DOKPLOY_CUSTOM_HEADERS),
             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),
+            redactEnv,
+            redactFields,
         };
     }
 }
 export function getClientConfig() {
     return ConfigManager.getInstance().getConfig();
 }
+function parseBoolean(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized))
+        return true;
+    if (["false", "0", "no", "off", ""].includes(normalized))
+        return false;
+    return fallback;
+}

package/build/utils/redactSensitive.js

@@ -0,0 +1,80 @@
+export const DEFAULT_REDACTED_FIELDS = [
+    "env",
+    "buildArgs",
+    "composeFile",
+    "dockerCompose",
+    "environment",
+    "buildSecrets",
+    "previewBuildSecrets",
+    "password",
+    "currentPassword",
+    "appPassword",
+    "databasePassword",
+    "databaseRootPassword",
+    "redisPassword",
+    "mariadbPassword",
+    "mongoPassword",
+    "mysqlPassword",
+    "postgresPassword",
+    "registryPassword",
+    "token",
+    "accessToken",
+    "appToken",
+    "apiToken",
+    "botToken",
+    "refreshToken",
+    "secret",
+    "clientSecret",
+    "apiKey",
+    "secretAccessKey",
+    "accessKey",
+    "licenseKey",
+    "userKey",
+    "privateKey",
+    "privateKeyPass",
+    "encPrivateKey",
+    "encPrivateKeyPass",
+    "sshKey",
+    "sshPrivateKey",
+    "customGitSSHKey",
+    "dockerAuth",
+];
+const REDACTED_PLACEHOLDER = "[REDACTED]";
+export function redactSensitive(data, fields) {
+    if (fields.length === 0)
+        return data;
+    const lowered = new Set(fields.map((f) => f.toLowerCase()));
+    return walk(data, lowered, new WeakSet());
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function walk(value, fields, seen) {
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        return value.map((item) => walk(item, fields, seen));
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        const out = Object.create(null);
+        for (const [key, val] of Object.entries(value)) {
+            if (key === "__proto__" || key === "constructor" || key === "prototype")
+                continue;
+            if (fields.has(key.toLowerCase())) {
+                out[key] = val === null || val === undefined ? val : REDACTED_PLACEHOLDER;
+            }
+            else {
+                out[key] = walk(val, fields, seen);
+            }
+        }
+        return out;
+    }
+    return value;
+}

package/build/utils/responseFormatter.js

@@ -3,7 +3,7 @@ export class ResponseFormatter {
         const responseData = {
             success: true,
             message,
-            ...(data && typeof data === "object" && data !== null ? { data } : {}),
+            ...(data !== undefined && data !== null ? { data } : {}),
         };
         return {
             content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokploy/mcp",
-  "version": "0.29.2",
+  "version": "0.29.4",
   "description": "MCP Server for Dokploy API",
   "main": "build/index.js",
   "bin": {
@@ -30,14 +30,16 @@
     "@modelcontextprotocol/sdk": "^1.12.0",
     "axios": "^1.9.0",
     "hono": "^4.12.12",
-    "zod": "^3.25.28"
+    "zod": "^3.25.28",
+    "zod-to-json-schema": "^3.25.2"
   },
   "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"
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.6"
   },
   "scripts": {
     "build": "pnpm run clean && tsc && chmod 755 build/index.js",
@@ -57,6 +59,6 @@
     "type-check": "tsc --noEmit",
     "clean": "rm -rf build",
     "precommit": "biome check && pnpm run type-check",
-    "test": "echo \"Error: no test spcified\" && exit 1"
+    "test": "vitest run"
   }
 }