@vibetools/dokploy-mcp 0.4.0

package/dist/api/client.d.ts

@@ -0,0 +1,11 @@
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    readonly endpoint: string;
+    constructor(status: number, statusText: string, body: unknown, endpoint: string);
+}
+export declare const api: {
+    get: <T = unknown>(path: string, params?: Record<string, unknown>) => Promise<T>;
+    post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+};

package/dist/api/client.js

@@ -0,0 +1,103 @@
+import { resolveConfig } from '../config/resolver.js';
+function getConfig() {
+    const resolved = resolveConfig();
+    if (!resolved) {
+        throw new Error([
+            'Dokploy MCP is not configured. Set up credentials using one of these methods:',
+            '',
+            '  1. Run: npx @vibetools/dokploy-mcp setup',
+            '  2. Set environment variables: DOKPLOY_URL and DOKPLOY_API_KEY',
+            '',
+            'Get your API key from Dokploy Settings > API.',
+        ].join('\n'));
+    }
+    return {
+        baseUrl: resolved.url.replace(/\/+$/, ''),
+        apiKey: resolved.apiKey,
+        timeout: resolved.timeout,
+    };
+}
+let _config = null;
+function config() {
+    _config ??= getConfig();
+    return _config;
+}
+export class ApiError extends Error {
+    status;
+    statusText;
+    body;
+    endpoint;
+    constructor(status, statusText, body, endpoint) {
+        const msg = typeof body === 'object' && body !== null && 'message' in body
+            ? body.message
+            : statusText;
+        super(`Dokploy API error (${status}): ${msg}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.endpoint = endpoint;
+        this.name = 'ApiError';
+    }
+}
+function buildQueryString(body) {
+    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();
+}
+function isAbortError(error) {
+    return error instanceof DOMException || (error instanceof Error && error.name === 'AbortError');
+}
+async function request(method, path, body) {
+    const { baseUrl, apiKey, timeout } = config();
+    const qs = method === 'GET' ? buildQueryString(body) : '';
+    const url = qs ? `${baseUrl}${path}?${qs}` : `${baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                'x-api-key': apiKey,
+            },
+            body: method === 'POST' && body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = text;
+        }
+        if (!response.ok) {
+            throw new ApiError(response.status, response.statusText, data, path);
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw error;
+        }
+        if (isAbortError(error)) {
+            throw new Error(`Request to ${path} timed out after ${timeout}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const api = {
+    get: (path, params) => request('GET', path, params),
+    post: (path, body) => request('POST', path, body),
+};

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function runCli(args: string[]): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,48 @@
+export async function runCli(args) {
+    const command = args[0];
+    switch (command) {
+        case 'setup':
+        case 'init':
+        case 'auth': {
+            const { runSetup } = await import('./setup.js');
+            await runSetup();
+            break;
+        }
+        case 'version':
+        case '--version':
+        case '-v': {
+            const { readFileSync } = await import('node:fs');
+            const { fileURLToPath } = await import('node:url');
+            const { dirname, join } = await import('node:path');
+            const currentDir = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(join(currentDir, '..', '..', 'package.json'), 'utf8'));
+            console.log(`@vibetools/dokploy-mcp v${pkg.version}`);
+            break;
+        }
+        default:
+            printHelp();
+            break;
+    }
+}
+function printHelp() {
+    console.log(`
+@vibetools/dokploy-mcp - MCP server for the Dokploy API
+
+Usage:
+  npx @vibetools/dokploy-mcp              Start MCP server (stdio transport)
+  npx @vibetools/dokploy-mcp setup        Configure credentials and MCP client
+  npx @vibetools/dokploy-mcp version      Show version
+
+Commands:
+  setup, init, auth    Interactive setup wizard
+  version, -v          Show version number
+
+Environment Variables:
+  DOKPLOY_URL          Dokploy panel URL (e.g. https://panel.example.com)
+  DOKPLOY_API_KEY      API key from Dokploy Settings
+  DOKPLOY_TIMEOUT      Request timeout in ms (default: 30000)
+
+Documentation:
+  https://github.com/vcode-sh/dokploy-mcp
+`);
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1 @@
+export declare function runSetup(): Promise<void>;

package/dist/cli/setup.js

@@ -0,0 +1,112 @@
+import * as p from '@clack/prompts';
+import { resolveConfig, saveConfig, validateCredentials } from '../config/resolver.js';
+import { getConfigFilePath } from '../config/types.js';
+async function promptCredentials() {
+    const url = await p.text({
+        message: 'Dokploy server URL',
+        placeholder: 'https://panel.example.com',
+        validate: (value) => {
+            if (!value?.trim())
+                return 'URL is required';
+            try {
+                new URL(value.trim());
+            }
+            catch {
+                return 'Please enter a valid URL (e.g. https://panel.example.com)';
+            }
+        },
+    });
+    if (p.isCancel(url)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    const apiKey = await p.password({
+        message: 'API key (from Dokploy Settings > API)',
+        validate: (value) => {
+            if (!value?.trim())
+                return 'API key is required';
+        },
+    });
+    if (p.isCancel(apiKey)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    return { url: url.trim(), apiKey: apiKey.trim() };
+}
+const sourceLabels = {
+    env: 'environment variables',
+    'config-file': 'config file',
+    'dokploy-cli': 'Dokploy CLI config',
+};
+export async function runSetup() {
+    p.intro('@vibetools/dokploy-mcp setup');
+    // 1. Check for existing configuration
+    const existing = resolveConfig();
+    let url;
+    let apiKey;
+    if (existing) {
+        const sourceLabel = sourceLabels[existing.source] ?? existing.source;
+        const configFilePath = existing.source === 'config-file' ? ` (${getConfigFilePath()})` : '';
+        p.log.info(`Found existing credentials from ${sourceLabel}${configFilePath}`);
+        p.log.info(`URL: ${existing.url}`);
+        const useExisting = await p.confirm({
+            message: 'Use existing credentials?',
+        });
+        if (p.isCancel(useExisting)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        if (useExisting) {
+            url = existing.url;
+            apiKey = existing.apiKey;
+        }
+        else {
+            const result = await promptCredentials();
+            url = result.url;
+            apiKey = result.apiKey;
+        }
+    }
+    else {
+        p.log.info('No existing configuration found.');
+        const result = await promptCredentials();
+        url = result.url;
+        apiKey = result.apiKey;
+    }
+    // 2. Validate credentials against the Dokploy API
+    const s = p.spinner();
+    s.start('Validating credentials...');
+    const validation = await validateCredentials(url, apiKey);
+    if (!validation.valid) {
+        s.stop('Validation failed');
+        p.log.error(validation.error ?? 'Could not connect to Dokploy server');
+        p.outro('Please check your URL and API key and try again.');
+        process.exit(1);
+    }
+    s.stop('Credentials validated successfully');
+    if (validation.user)
+        p.log.success(`Authenticated as: ${validation.user}`);
+    if (validation.version)
+        p.log.success(`Dokploy version: ${validation.version}`);
+    // Use the normalized URL if the validator resolved one
+    if (validation.resolvedUrl)
+        url = validation.resolvedUrl;
+    // 3. Save config to disk
+    const configPath = saveConfig({ url, apiKey });
+    p.log.success(`Config saved to ${configPath}`);
+    // 4. Show MCP client configuration snippet
+    const mcpConfig = JSON.stringify({
+        mcpServers: {
+            dokploy: {
+                command: 'npx',
+                args: ['@vibetools/dokploy-mcp'],
+            },
+        },
+    }, null, 2);
+    p.note(mcpConfig, 'Add to your MCP client config');
+    p.log.step('Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json');
+    p.log.step('Claude Code:    .claude/settings.json or .mcp.json');
+    p.log.step('Cursor:         ~/.cursor/mcp.json');
+    p.log.step('VS Code:        .vscode/mcp.json');
+    // 5. Done
+    p.outro('Setup complete! Restart your MCP client to connect.');
+}

package/dist/config/resolver.d.ts

@@ -0,0 +1,38 @@
+import type { DokployConfig, ResolvedConfig } from './types.js';
+/**
+ * Normalizes a Dokploy URL to the tRPC API base.
+ * Accepts any of these formats:
+ *   https://panel.example.com
+ *   https://panel.example.com/api
+ *   https://panel.example.com/api/trpc
+ * Always returns https://panel.example.com/api/trpc
+ */
+export declare function normalizeUrl(url: string): string;
+/**
+ * Resolves Dokploy configuration from multiple sources in priority order:
+ * 1. Environment variables (DOKPLOY_URL + DOKPLOY_API_KEY)
+ * 2. Config file (~/.config/dokploy-mcp/config.json)
+ * 3. Dokploy CLI config (@dokploy/cli global install)
+ *
+ * URLs are automatically normalized to the tRPC API base path.
+ * Returns null if no configuration is found.
+ */
+export declare function resolveConfig(): ResolvedConfig | null;
+/**
+ * Saves configuration to the config file.
+ * Creates the config directory if it doesn't exist.
+ * Returns the file path where the config was saved.
+ */
+export declare function saveConfig(config: DokployConfig): string;
+export interface ValidationResult {
+    valid: boolean;
+    resolvedUrl?: string;
+    user?: string;
+    version?: string;
+    error?: string;
+}
+/**
+ * Validates Dokploy credentials by making API requests.
+ * Tries to detect the correct URL format and validates the API key.
+ */
+export declare function validateCredentials(url: string, apiKey: string): Promise<ValidationResult>;

package/dist/config/resolver.js

@@ -0,0 +1,290 @@
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir, getConfigFilePath } from './types.js';
+/**
+ * Normalizes a Dokploy URL to the tRPC API base.
+ * Accepts any of these formats:
+ *   https://panel.example.com
+ *   https://panel.example.com/api
+ *   https://panel.example.com/api/trpc
+ * Always returns https://panel.example.com/api/trpc
+ */
+export function normalizeUrl(url) {
+    const stripped = url.replace(/\/+$/, '');
+    if (stripped.endsWith('/api/trpc'))
+        return stripped;
+    if (stripped.endsWith('/api'))
+        return `${stripped}/trpc`;
+    return `${stripped}/api/trpc`;
+}
+/**
+ * Resolves Dokploy configuration from multiple sources in priority order:
+ * 1. Environment variables (DOKPLOY_URL + DOKPLOY_API_KEY)
+ * 2. Config file (~/.config/dokploy-mcp/config.json)
+ * 3. Dokploy CLI config (@dokploy/cli global install)
+ *
+ * URLs are automatically normalized to the tRPC API base path.
+ * Returns null if no configuration is found.
+ */
+export function resolveConfig() {
+    const timeout = Number.parseInt(process.env.DOKPLOY_TIMEOUT || '30000', 10);
+    // 1. Environment variables (highest priority)
+    const envUrl = process.env.DOKPLOY_URL;
+    const envApiKey = process.env.DOKPLOY_API_KEY;
+    if (envUrl && envApiKey) {
+        return {
+            url: normalizeUrl(envUrl),
+            apiKey: envApiKey,
+            source: 'env',
+            timeout,
+        };
+    }
+    // 2. Config file
+    const configFromFile = readConfigFile();
+    if (configFromFile) {
+        return {
+            url: normalizeUrl(configFromFile.url),
+            apiKey: configFromFile.apiKey,
+            source: 'config-file',
+            timeout,
+        };
+    }
+    // 3. Dokploy CLI config
+    const configFromCli = readDokployCliConfig();
+    if (configFromCli) {
+        return {
+            url: normalizeUrl(configFromCli.url),
+            apiKey: configFromCli.apiKey,
+            source: 'dokploy-cli',
+            timeout,
+        };
+    }
+    return null;
+}
+/**
+ * Reads the config file at the platform-appropriate location.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+function readConfigFile() {
+    const filePath = getConfigFilePath();
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    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 };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads the Dokploy CLI global config.
+ * The CLI stores { url, token } where url is the bare panel URL.
+ * Maps token to apiKey; URL normalization is handled by resolveConfig().
+ */
+function readDokployCliConfig() {
+    try {
+        const globalRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
+        const cliConfigPath = join(globalRoot, '@dokploy', 'cli', 'config.json');
+        if (!existsSync(cliConfigPath)) {
+            return null;
+        }
+        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 };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Saves configuration to the config file.
+ * Creates the config directory if it doesn't exist.
+ * Returns the file path where the config was saved.
+ */
+export function saveConfig(config) {
+    const configDir = getConfigDir();
+    const filePath = getConfigFilePath();
+    mkdirSync(configDir, { recursive: true });
+    const data = {
+        url: config.url,
+        apiKey: config.apiKey,
+    };
+    writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    return filePath;
+}
+/**
+ * Builds a list of candidate base URLs to try for validation.
+ * Handles bare panel URLs, /api, and /api/trpc suffixes.
+ */
+function buildCandidateUrls(url) {
+    const normalized = url.replace(/\/+$/, '');
+    if (normalized.endsWith('/api/trpc')) {
+        return [normalized];
+    }
+    if (normalized.endsWith('/api')) {
+        // User may have meant /api/trpc — try both
+        return [`${normalized}/trpc`, normalized];
+    }
+    // Bare panel URL — try the most common path first
+    return [`${normalized}/api/trpc`, `${normalized}/api`, normalized];
+}
+/**
+ * Validates Dokploy credentials by making API requests.
+ * Tries to detect the correct URL format and validates the API key.
+ */
+export async function validateCredentials(url, apiKey) {
+    const normalizedUrl = url.replace(/\/+$/, '');
+    const candidates = buildCandidateUrls(normalizedUrl);
+    for (const baseUrl of candidates) {
+        const result = await tryValidate(baseUrl, apiKey);
+        if (result.valid) {
+            return result;
+        }
+        // Auth error means the URL was right but the key was wrong — stop trying
+        if (result.error &&
+            !result.error.includes('not reachable') &&
+            !result.error.includes('Not Found')) {
+            return result;
+        }
+    }
+    return {
+        valid: false,
+        error: `Could not connect to Dokploy at ${normalizedUrl}. Ensure the URL is correct and the server is running.`,
+    };
+}
+function apiHeaders(apiKey) {
+    return { Accept: 'application/json', 'x-api-key': apiKey };
+}
+function mapAuthError(status, statusText) {
+    if (status === 401 || status === 403) {
+        return { valid: false, error: 'Invalid API key. Check your key in Dokploy Settings > API.' };
+    }
+    if (status === 404) {
+        return { valid: false, error: 'Not Found' };
+    }
+    return { valid: false, error: `API returned HTTP ${status}: ${statusText}` };
+}
+/**
+ * Unwraps a tRPC response envelope: { result: { data: { json: T } } } → T
+ * Falls back to the raw data if it's not in tRPC format.
+ */
+function unwrapTrpc(data) {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    const outer = data;
+    if (typeof outer.result !== 'object' || outer.result === null)
+        return data;
+    const result = outer.result;
+    if (typeof result.data !== 'object' || result.data === null)
+        return data;
+    const inner = result.data;
+    return 'json' in inner ? inner.json : data;
+}
+function parseUser(data) {
+    const unwrapped = unwrapTrpc(data);
+    if (typeof unwrapped !== 'object' || unwrapped === null)
+        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;
+}
+async function fetchVersion(baseUrl, apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const response = await fetch(`${baseUrl}/settings.getDokployVersion`, {
+            method: 'GET',
+            headers: apiHeaders(apiKey),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            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;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function tryValidate(baseUrl, apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    try {
+        // Use user.get — the standard Dokploy tRPC endpoint for current user
+        const authResponse = await fetch(`${baseUrl}/user.get`, {
+            method: 'GET',
+            headers: apiHeaders(apiKey),
+            signal: controller.signal,
+        });
+        if (!authResponse.ok) {
+            return mapAuthError(authResponse.status, authResponse.statusText);
+        }
+        const authData = await authResponse.json();
+        const user = parseUser(authData);
+        const version = await fetchVersion(baseUrl, apiKey);
+        return { valid: true, resolvedUrl: baseUrl, user, version };
+    }
+    catch (error) {
+        if (error instanceof DOMException || (error instanceof Error && error.name === 'AbortError')) {
+            return { valid: false, error: `Server at ${baseUrl} is not reachable (request timed out).` };
+        }
+        return {
+            valid: false,
+            error: `Server at ${baseUrl} is not reachable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/config/types.d.ts

@@ -0,0 +1,25 @@
+export interface DokployConfig {
+    url: string;
+    apiKey: string;
+}
+export type ConfigSource = 'env' | 'config-file' | 'dokploy-cli';
+export interface ResolvedConfig extends DokployConfig {
+    source: ConfigSource;
+    timeout: number;
+}
+export interface ConfigFile {
+    url: string;
+    apiKey: string;
+}
+/**
+ * Returns the platform-appropriate config directory for dokploy-mcp.
+ *
+ * - macOS: ~/.config/dokploy-mcp
+ * - Linux: $XDG_CONFIG_HOME/dokploy-mcp or ~/.config/dokploy-mcp
+ * - Windows: %APPDATA%/dokploy-mcp
+ */
+export declare function getConfigDir(): string;
+/**
+ * Returns the full path to the config file.
+ */
+export declare function getConfigFilePath(): string;

package/dist/config/types.js

@@ -0,0 +1,33 @@
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Returns the platform-appropriate config directory for dokploy-mcp.
+ *
+ * - macOS: ~/.config/dokploy-mcp
+ * - Linux: $XDG_CONFIG_HOME/dokploy-mcp or ~/.config/dokploy-mcp
+ * - Windows: %APPDATA%/dokploy-mcp
+ */
+export function getConfigDir() {
+    const os = platform();
+    if (os === 'win32') {
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return join(appData, 'dokploy-mcp');
+        }
+        return join(homedir(), 'AppData', 'Roaming', 'dokploy-mcp');
+    }
+    if (os === 'linux') {
+        const xdgConfig = process.env.XDG_CONFIG_HOME;
+        if (xdgConfig) {
+            return join(xdgConfig, 'dokploy-mcp');
+        }
+    }
+    // macOS and Linux fallback
+    return join(homedir(), '.config', 'dokploy-mcp');
+}
+/**
+ * Returns the full path to the config file.
+ */
+export function getConfigFilePath() {
+    return join(getConfigDir(), 'config.json');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};