@vibetools/dokploy-mcp 0.4.0 → 1.0.0

package/dist/api/client.js

@@ -1,4 +1,5 @@
 import { resolveConfig } from '../config/resolver.js';
+const DEFAULT_TIMEOUT = 30_000;
 function getConfig() {
     const resolved = resolveConfig();
     if (!resolved) {
@@ -14,7 +15,7 @@ function getConfig() {
     return {
         baseUrl: resolved.url.replace(/\/+$/, ''),
         apiKey: resolved.apiKey,
-        timeout: resolved.timeout,
+        timeout: resolved.timeout || DEFAULT_TIMEOUT,
     };
 }
 let _config = null;
@@ -40,17 +41,18 @@ export class ApiError extends Error {
     }
 }
 function buildQueryString(body) {
-    if (!body || typeof body !== 'object') {
+    if (!body || typeof body !== 'object')
         return '';
-    }
-    const params = new URLSearchParams();
-    for (const [k, v] of Object.entries(body)) {
-        if (v !== undefined && v !== null) {
-            params.set(k, String(v));
-        }
-    }
-    return params.toString();
+    const entries = Object.entries(body)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => [k, String(v)]);
+    return entries.length > 0 ? new URLSearchParams(entries).toString() : '';
 }
+/**
+ * Checks whether an error was caused by an aborted fetch.
+ * Both checks are needed: older Node versions throw DOMException,
+ * while newer versions throw an Error with name 'AbortError'.
+ */
 function isAbortError(error) {
     return error instanceof DOMException || (error instanceof Error && error.name === 'AbortError');
 }

package/dist/config/resolver.js

@@ -1,7 +1,28 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { z } from 'zod';
 import { getConfigDir, getConfigFilePath } from './types.js';
+const configFileSchema = z.object({
+    url: z.string().min(1),
+    apiKey: z.string().min(1),
+});
+const dokployCliSchema = z.object({
+    url: z.string().min(1),
+    token: z.string().min(1),
+});
+const userSchema = z
+    .object({
+    email: z.string().optional(),
+    user: z
+        .object({
+        email: z.string().optional(),
+        firstName: z.string().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+const versionSchema = z.union([z.string(), z.object({ version: z.string() }).passthrough()]);
 /**
  * Normalizes a Dokploy URL to the tRPC API base.
  * Accepts any of these formats:
@@ -74,20 +95,8 @@ function readConfigFile() {
     try {
         const content = readFileSync(filePath, 'utf8');
         const parsed = JSON.parse(content);
-        if (typeof parsed !== 'object' ||
-            parsed === null ||
-            !('url' in parsed) ||
-            !('apiKey' in parsed)) {
-            return null;
-        }
-        const record = parsed;
-        if (typeof record.url !== 'string' || typeof record.apiKey !== 'string') {
-            return null;
-        }
-        if (!(record.url && record.apiKey)) {
-            return null;
-        }
-        return { url: record.url, apiKey: record.apiKey };
+        const result = configFileSchema.safeParse(parsed);
+        return result.success ? result.data : null;
     }
     catch {
         return null;
@@ -107,20 +116,8 @@ function readDokployCliConfig() {
         }
         const content = readFileSync(cliConfigPath, 'utf8');
         const parsed = JSON.parse(content);
-        if (typeof parsed !== 'object' ||
-            parsed === null ||
-            !('url' in parsed) ||
-            !('token' in parsed)) {
-            return null;
-        }
-        const record = parsed;
-        if (typeof record.url !== 'string' || typeof record.token !== 'string') {
-            return null;
-        }
-        if (!(record.url && record.token)) {
-            return null;
-        }
-        return { url: record.url, apiKey: record.token };
+        const result = dokployCliSchema.safeParse(parsed);
+        return result.success ? { url: result.data.url, apiKey: result.data.token } : null;
     }
     catch {
         return null;
@@ -212,21 +209,11 @@ function unwrapTrpc(data) {
 }
 function parseUser(data) {
     const unwrapped = unwrapTrpc(data);
-    if (typeof unwrapped !== 'object' || unwrapped === null)
+    const result = userSchema.safeParse(unwrapped);
+    if (!result.success)
         return undefined;
-    const record = unwrapped;
-    // Top-level email/name
-    if (typeof record.email === 'string')
-        return record.email;
-    // Nested user object (tRPC user.get response)
-    if (typeof record.user === 'object' && record.user !== null) {
-        const user = record.user;
-        if (typeof user.email === 'string')
-            return user.email;
-        if (typeof user.firstName === 'string')
-            return user.firstName;
-    }
-    return undefined;
+    const { email, user } = result.data;
+    return email ?? user?.email ?? user?.firstName;
 }
 async function fetchVersion(baseUrl, apiKey) {
     const controller = new AbortController();
@@ -241,14 +228,10 @@ async function fetchVersion(baseUrl, apiKey) {
             return undefined;
         const data = await response.json();
         const unwrapped = unwrapTrpc(data);
-        if (typeof unwrapped === 'string')
-            return unwrapped;
-        if (typeof unwrapped === 'object' && unwrapped !== null) {
-            const record = unwrapped;
-            if (typeof record.version === 'string')
-                return record.version;
-        }
-        return undefined;
+        const result = versionSchema.safeParse(unwrapped);
+        if (!result.success)
+            return undefined;
+        return typeof result.data === 'string' ? result.data : result.data.version;
     }
     catch {
         return undefined;

package/dist/server.js

@@ -3,7 +3,7 @@ import { allTools } from './tools/index.js';
 export function createServer() {
     const server = new McpServer({
         name: 'dokploy-mcp-server',
-        version: '0.1.0',
+        version: '1.0.0',
     });
     for (const tool of allTools) {
         server.registerTool(tool.name, {

package/dist/tools/_database.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { type ToolDefinition } from './_factory.js';
+type AnyZodObject = z.ZodObject;
+export interface DatabaseConfig {
+    type: string;
+    idField: string;
+    displayName: string;
+    defaultImage: string;
+    createFields: AnyZodObject;
+}
+export declare function createDatabaseTools(config: DatabaseConfig): ToolDefinition[];
+export {};

package/dist/tools/_database.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { getTool, postTool } from './_factory.js';
+export function createDatabaseTools(config) {
+    const { type, idField, displayName, defaultImage, createFields } = config;
+    const idSchema = z
+        .object({ [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`) })
+        .strict();
+    function tool(action, title, description, schema, opts = {}) {
+        const endpoint = `${type}.${action}`;
+        const name = `dokploy_${type}_${action.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)}`;
+        if (opts.get) {
+            return getTool({ name, title, description, schema, endpoint, annotations: opts.annotations });
+        }
+        return postTool({ name, title, description, schema, endpoint, annotations: opts.annotations });
+    }
+    const one = tool('one', `Get ${displayName} Details`, `Retrieve detailed information about a specific ${displayName} database managed by Dokploy. Returns the full configuration including connection settings, resource limits, environment variables, and current status. Requires the unique ${displayName} database ID.`, idSchema, { get: true });
+    const create = tool('create', `Create ${displayName} Database`, `Create a new ${displayName} database instance inside a Dokploy project. Requires a display name, app-level identifier, and the target project ID. Optionally specify a Docker image, description, or remote server. Returns the newly created database record.`, z
+        .object({
+        name: z.string().min(1).describe('Display name for the database'),
+        appName: z.string().min(1).describe('Unique app-level identifier'),
+        ...createFields.shape,
+        projectId: z.string().min(1).describe('Project ID to create the database in'),
+        dockerImage: z.string().optional().describe(`Docker image (default: ${defaultImage})`),
+        description: z.string().nullable().optional().describe('Optional description'),
+        serverId: z.string().nullable().optional().describe('Target server ID (null for local)'),
+    })
+        .strict());
+    const update = tool('update', `Update ${displayName} Database`, `Update the configuration of an existing ${displayName} database in Dokploy. Supports modifying the display name, Docker image, resource limits (CPU and memory), custom start command, environment variables, and external port. Requires the ${displayName} database ID. Only the provided fields are updated.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        name: z.string().min(1).optional().describe('Display name'),
+        appName: z.string().min(1).optional().describe('App-level identifier'),
+        description: z.string().nullable().optional().describe('Description'),
+        dockerImage: z.string().optional().describe('Docker image'),
+        memoryReservation: z.number().nullable().optional().describe('Memory reservation in MB'),
+        memoryLimit: z.number().nullable().optional().describe('Memory limit in MB'),
+        cpuReservation: z.number().nullable().optional().describe('CPU reservation'),
+        cpuLimit: z.number().nullable().optional().describe('CPU limit'),
+        command: z.string().nullable().optional().describe('Custom start command'),
+        env: z.string().nullable().optional().describe('Environment variables'),
+        externalPort: z.number().nullable().optional().describe('External port'),
+    })
+        .strict());
+    const remove = tool('remove', `Remove ${displayName} Database`, `Permanently delete a ${displayName} database from Dokploy. This action removes the database container, its data, and all associated configuration. Requires the ${displayName} database ID. This operation is destructive and cannot be undone.`, idSchema, { annotations: { destructiveHint: true } });
+    const move = tool('move', `Move ${displayName} Database`, `Move a ${displayName} database from its current project to a different project within Dokploy. Requires the ${displayName} database ID and the destination project ID. The database configuration and data are preserved during the move.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        targetProjectId: z.string().min(1).describe('Destination project ID'),
+    })
+        .strict());
+    const deploy = tool('deploy', `Deploy ${displayName} Database`, `Deploy a ${displayName} database container in Dokploy. Triggers the build and start process for the specified database. Requires the ${displayName} database ID. Returns the deployment status.`, idSchema);
+    const start = tool('start', `Start ${displayName} Database`, `Start a previously stopped ${displayName} database container in Dokploy. The database must already be deployed. Requires the ${displayName} database ID. Returns the updated status after starting.`, idSchema);
+    const stop = tool('stop', `Stop ${displayName} Database`, `Stop a running ${displayName} database container in Dokploy. The database data is preserved but the container will no longer accept connections. Requires the ${displayName} database ID. This is a destructive action as it interrupts active connections.`, idSchema, { annotations: { destructiveHint: true } });
+    const reload = tool('reload', `Reload ${displayName} Database`, `Reload the ${displayName} database container in Dokploy without a full restart. Applies configuration changes that do not require a rebuild. Requires the ${displayName} database ID and the app-level identifier. Returns the reload status.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        appName: z.string().min(1).describe('App-level identifier'),
+    })
+        .strict());
+    const rebuild = tool('rebuild', `Rebuild ${displayName} Database`, `Rebuild the ${displayName} database container from scratch in Dokploy. This tears down the existing container and recreates it with the current configuration. Requires the ${displayName} database ID. Useful after changing the Docker image or when the container is in a broken state.`, idSchema);
+    const changeStatus = tool('changeStatus', `Change ${displayName} Status`, `Manually set the application status of a ${displayName} database in Dokploy. Accepts one of: idle, running, done, or error. Requires the ${displayName} database ID and the new status value. Useful for correcting a stale or incorrect status.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        applicationStatus: z
+            .enum(['idle', 'running', 'done', 'error'])
+            .describe('New application status'),
+    })
+        .strict());
+    const saveExternalPort = tool('saveExternalPort', `Save ${displayName} External Port`, `Set or clear the external port mapping for a ${displayName} database in Dokploy. When set, the database is accessible from outside the Docker network on the specified port. Pass null to remove the external port. Requires the ${displayName} database ID.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        externalPort: z.number().nullable().describe('External port number (null to remove)'),
+    })
+        .strict());
+    const saveEnvironment = tool('saveEnvironment', `Save ${displayName} Environment`, `Overwrite the environment variables for a ${displayName} database in Dokploy. Replaces all existing environment variables with the provided value. Pass the variables as a single string (one per line, KEY=VALUE format). Requires the ${displayName} database ID.`, z
+        .object({
+        [idField]: z.string().min(1).describe(`Unique ${displayName} database ID`),
+        env: z.string().nullable().optional().describe('Environment variables as a string'),
+    })
+        .strict());
+    return [
+        one,
+        create,
+        update,
+        remove,
+        move,
+        deploy,
+        start,
+        stop,
+        reload,
+        rebuild,
+        changeStatus,
+        saveExternalPort,
+        saveEnvironment,
+    ];
+}

package/dist/tools/_factory.d.ts

@@ -28,7 +28,7 @@ export declare function createTool<T extends AnyZodObject>(def: {
     title: string;
     description: string;
     schema: T;
-    annotations: ToolAnnotations;
+    annotations?: Partial<ToolAnnotations>;
     handler: (params: {
         input: z.infer<T>;
         api: typeof api;

package/dist/tools/_factory.js

@@ -16,19 +16,22 @@ function error(message, details) {
         isError: true,
     };
 }
+const ERROR_MAP = {
+    401: ['Authentication failed', () => 'Check your DOKPLOY_API_KEY environment variable.'],
+    403: ['Permission denied', () => 'Your API key lacks permission for this operation.'],
+    404: ['Resource not found', (err) => err.message],
+    422: [
+        'Validation error',
+        (err) => typeof err.body === 'object' && err.body !== null ? JSON.stringify(err.body) : err.message,
+    ],
+};
 function mapApiError(err) {
-    switch (err.status) {
-        case 401:
-            return error('Authentication failed', 'Check your DOKPLOY_API_KEY environment variable.');
-        case 403:
-            return error('Permission denied', 'Your API key lacks permission for this operation.');
-        case 404:
-            return error('Resource not found', err.message);
-        case 422:
-            return error('Validation error', typeof err.body === 'object' && err.body !== null ? JSON.stringify(err.body) : err.message);
-        default:
-            return error(`Dokploy API error (${err.status})`, err.message);
+    const entry = ERROR_MAP[err.status];
+    if (entry) {
+        const [message, getDetails] = entry;
+        return error(message, getDetails(err));
     }
+    return error(`Dokploy API error (${err.status})`, err.message);
 }
 export function createTool(def) {
     return {
@@ -57,7 +60,7 @@ export function postTool(opts) {
         title: opts.title,
         description: opts.description,
         schema: opts.schema,
-        annotations: { openWorldHint: true, ...opts.annotations },
+        annotations: opts.annotations,
         handler: async ({ input, api }) => api.post(opts.endpoint, input),
     });
 }
@@ -70,7 +73,6 @@ export function getTool(opts) {
         annotations: {
             readOnlyHint: true,
             idempotentHint: true,
-            openWorldHint: true,
             ...opts.annotations,
         },
         handler: async ({ input, api }) => {

package/dist/tools/mariadb.d.ts

@@ -1,2 +1 @@
-import { type ToolDefinition } from './_factory.js';
-export declare const mariadbTools: ToolDefinition[];
+export declare const mariadbTools: import("./_factory.js").ToolDefinition[];

package/dist/tools/mariadb.js

@@ -1,170 +1,14 @@
 import { z } from 'zod';
-import { getTool, postTool } from './_factory.js';
-// ── helpers ──────────────────────────────────────────────────────────
-const mdbId = z.string().min(1).describe('Unique MariaDB database ID');
-const DB = 'mariadb';
-// ── tools ────────────────────────────────────────────────────────────
-const one = getTool({
-    name: `dokploy_${DB}_one`,
-    title: 'Get MariaDB Details',
-    description: 'Retrieve the full configuration and status details of a MariaDB database managed by Dokploy. Requires the unique MariaDB database ID. Returns all metadata including name, image, resource limits, environment variables, and current application status.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.one`,
-});
-const create = postTool({
-    name: `dokploy_${DB}_create`,
-    title: 'Create MariaDB Database',
-    description: 'Create a new MariaDB database instance inside a Dokploy project. Requires a display name, app-level identifier, database name, user credentials, root password, and the target project ID. Optionally specify a Docker image, description, or remote server. Returns the newly created database record.',
-    schema: z
-        .object({
-        name: z.string().min(1).describe('Display name for the database'),
-        appName: z.string().min(1).describe('Unique app-level identifier'),
+import { createDatabaseTools } from './_database.js';
+export const mariadbTools = createDatabaseTools({
+    type: 'mariadb',
+    idField: 'mariadbId',
+    displayName: 'MariaDB',
+    defaultImage: 'mariadb:11',
+    createFields: z.object({
         databaseName: z.string().min(1).describe('Name of the database to create'),
         databaseUser: z.string().min(1).describe('Database user'),
         databasePassword: z.string().min(1).describe('Database password'),
         databaseRootPassword: z.string().min(1).describe('Root password for MariaDB'),
-        projectId: z.string().min(1).describe('Project ID to create the database in'),
-        dockerImage: z.string().optional().describe('Docker image (default: mariadb:11)'),
-        description: z.string().nullable().optional().describe('Optional description'),
-        serverId: z.string().nullable().optional().describe('Target server ID (null for local)'),
-    })
-        .strict(),
-    endpoint: `${DB}.create`,
-});
-const update = postTool({
-    name: `dokploy_${DB}_update`,
-    title: 'Update MariaDB Database',
-    description: 'Update the configuration of an existing MariaDB database in Dokploy. Requires the MariaDB database ID and accepts optional fields such as name, Docker image, resource limits (memory and CPU), custom start command, environment variables, and external port. Returns the updated database configuration.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        name: z.string().min(1).optional().describe('Display name'),
-        appName: z.string().min(1).optional().describe('App-level identifier'),
-        description: z.string().nullable().optional().describe('Description'),
-        dockerImage: z.string().optional().describe('Docker image'),
-        memoryReservation: z.number().nullable().optional().describe('Memory reservation in MB'),
-        memoryLimit: z.number().nullable().optional().describe('Memory limit in MB'),
-        cpuReservation: z.number().nullable().optional().describe('CPU reservation'),
-        cpuLimit: z.number().nullable().optional().describe('CPU limit'),
-        command: z.string().nullable().optional().describe('Custom start command'),
-        env: z.string().nullable().optional().describe('Environment variables'),
-        externalPort: z.number().nullable().optional().describe('External port'),
-    })
-        .strict(),
-    endpoint: `${DB}.update`,
-});
-const remove = postTool({
-    name: `dokploy_${DB}_remove`,
-    title: 'Remove MariaDB Database',
-    description: 'Permanently delete a MariaDB database from Dokploy. Requires the MariaDB database ID. This is a destructive operation that removes the container, all associated data, and configuration. Returns the operation status confirming deletion.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.remove`,
-    annotations: { destructiveHint: true },
-});
-const move = postTool({
-    name: `dokploy_${DB}_move`,
-    title: 'Move MariaDB Database',
-    description: 'Move a MariaDB database from its current project to a different project within Dokploy. Requires the MariaDB database ID and the destination project ID. The database configuration and data remain intact during the move. Returns the operation status.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        targetProjectId: z.string().min(1).describe('Destination project ID'),
-    })
-        .strict(),
-    endpoint: `${DB}.move`,
-});
-const deploy = postTool({
-    name: `dokploy_${DB}_deploy`,
-    title: 'Deploy MariaDB Database',
-    description: 'Deploy a MariaDB database in Dokploy, pulling the configured Docker image and starting the container. Requires the MariaDB database ID. This triggers a full deployment lifecycle including image pull, container creation, and startup. Returns the deployment operation status.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.deploy`,
-});
-const start = postTool({
-    name: `dokploy_${DB}_start`,
-    title: 'Start MariaDB Database',
-    description: 'Start a previously stopped MariaDB database container in Dokploy. Requires the MariaDB database ID. The container will resume with its existing data and configuration. Returns the operation status.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.start`,
-});
-const stop = postTool({
-    name: `dokploy_${DB}_stop`,
-    title: 'Stop MariaDB Database',
-    description: 'Stop a currently running MariaDB database container in Dokploy. Requires the MariaDB database ID. The container will be gracefully stopped but its data and configuration are preserved for future restarts. Returns the operation status.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.stop`,
-    annotations: { destructiveHint: true },
-});
-const reload = postTool({
-    name: `dokploy_${DB}_reload`,
-    title: 'Reload MariaDB Database',
-    description: 'Reload the MariaDB database container in Dokploy without performing a full rebuild. Requires the MariaDB database ID and the app-level identifier. This restarts the container with its current configuration. Returns the operation status.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        appName: z.string().min(1).describe('App-level identifier'),
-    })
-        .strict(),
-    endpoint: `${DB}.reload`,
-});
-const rebuild = postTool({
-    name: `dokploy_${DB}_rebuild`,
-    title: 'Rebuild MariaDB Database',
-    description: 'Rebuild the MariaDB database container from scratch in Dokploy. Requires the MariaDB database ID. This tears down the existing container and recreates it using the current configuration, which is useful when the container state has become inconsistent. Returns the operation status.',
-    schema: z.object({ mariadbId: mdbId }).strict(),
-    endpoint: `${DB}.rebuild`,
-});
-const changeStatus = postTool({
-    name: `dokploy_${DB}_change_status`,
-    title: 'Change MariaDB Status',
-    description: 'Manually set the application status of a MariaDB database in Dokploy. Requires the MariaDB database ID and the desired status (idle, running, done, or error). This is typically used for administrative overrides when the reported status does not match reality. Returns the updated status.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        applicationStatus: z
-            .enum(['idle', 'running', 'done', 'error'])
-            .describe('New application status'),
-    })
-        .strict(),
-    endpoint: `${DB}.changeStatus`,
-});
-const saveExternalPort = postTool({
-    name: `dokploy_${DB}_save_external_port`,
-    title: 'Save MariaDB External Port',
-    description: 'Set or clear the external port mapping for a MariaDB database in Dokploy. Requires the MariaDB database ID and the desired external port number, or null to remove the external port mapping. This controls whether the database is accessible from outside the Docker network. Returns the operation status.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        externalPort: z.number().nullable().describe('External port number (null to remove)'),
-    })
-        .strict(),
-    endpoint: `${DB}.saveExternalPort`,
-});
-const saveEnvironment = postTool({
-    name: `dokploy_${DB}_save_environment`,
-    title: 'Save MariaDB Environment',
-    description: 'Overwrite the environment variables for a MariaDB database in Dokploy. Requires the MariaDB database ID and the environment variables as a string. This replaces all existing environment variables with the provided values. Returns the operation status.',
-    schema: z
-        .object({
-        mariadbId: mdbId,
-        env: z.string().nullable().optional().describe('Environment variables as a string'),
-    })
-        .strict(),
-    endpoint: `${DB}.saveEnvironment`,
+    }),
 });
-// ── export ───────────────────────────────────────────────────────────
-export const mariadbTools = [
-    one,
-    create,
-    update,
-    remove,
-    move,
-    deploy,
-    start,
-    stop,
-    reload,
-    rebuild,
-    changeStatus,
-    saveExternalPort,
-    saveEnvironment,
-];

package/dist/tools/mongo.d.ts

@@ -1,2 +1 @@
-import { type ToolDefinition } from './_factory.js';
-export declare const mongoTools: ToolDefinition[];
+export declare const mongoTools: import("./_factory.js").ToolDefinition[];