@vibetools/dokploy-mcp 1.0.0 → 2.0.0

package/README.md

@@ -2,15 +2,19 @@
 
 [![npm version](https://img.shields.io/npm/v/@vibetools/dokploy-mcp)](https://www.npmjs.com/package/@vibetools/dokploy-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+[![Node >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org/)
 
-MCP server for the Dokploy API. 196 tools across 23 modules. Your AI agent can now deploy apps, manage databases, configure domains, and handle backups -- without you touching a dashboard.
+MCP server for [Dokploy](https://dokploy.com). Two tools. 463 API procedures. Your AI agent can now deploy, configure, and manage your entire infrastructure without memorizing 377 endpoint definitions first.
 
-Forked from [Dokploy/mcp](https://github.com/Dokploy/mcp) and rebuilt with expanded API coverage, tool annotations, Zod v4 schemas, lazy config loading, and a setup wizard. The original had 67 tools. This one has 196. Standing on shoulders, etc.
+Most MCP servers dump hundreds of tool schemas into your context window and call it a day. This one doesn't. **Code Mode** gives your agent `search` and `execute` -- it finds what it needs from a compact API catalog, writes a workflow, and the sandbox runs the whole thing in one call. Create an app, set env vars, mount volumes, configure domains, deploy -- all in a single round-trip.
 
-## Quick Start
+The result: **99.8% fewer tokens** on tool definitions. Your context window can go back to doing its actual job.
 
-Grab your API key from **Dokploy Settings > Profile > API/CLI** and add this to your MCP client config:
+> Previously: 377 tools = ~92,354 tokens just to list them. Now: 2 tools = ~218 tokens. The math is embarrassing for everyone else.
+
+## Quick start
+
+Grab your API key from **Dokploy Settings > Profile > API/CLI**:
 
 ```json
 {
@@ -27,203 +31,98 @@ Grab your API key from **Dokploy Settings > Profile > API/CLI** and add this to
 }
 ```
 
-That's it. No setup wizard, no config files, no PhD.
-
-### Alternative: setup wizard
-
-If you prefer saving credentials to disk instead of env vars:
-
-```bash
-npx @vibetools/dokploy-mcp setup
-```
+Drop this into Claude Desktop, Claude Code, Cursor, VS Code, Windsurf -- anything that speaks MCP. Done. No ceremony.
 
-Validates credentials, saves to `~/.config/dokploy-mcp/config.json`, and shows you the minimal MCP config to copy. After that, the `env` block is optional.
+Already have the [Dokploy CLI](https://github.com/Dokploy/cli) authenticated? Skip the `env` block entirely. It just works.
 
-### Alternative: Dokploy CLI auto-detection
+Want a wizard? `npx @vibetools/dokploy-mcp setup` -- validates credentials, saves config, holds your hand exactly once.
 
-If you already have the [Dokploy CLI](https://github.com/Dokploy/cli) installed and authenticated -- zero config needed. It just works.
+## How it works
 
-## Features
+Your agent gets two tools:
 
-- **196 tools, 23 modules** -- applications, compose, databases (Postgres/MySQL/MariaDB/MongoDB/Redis), domains, backups, Docker, settings, and more
-- **Tool annotations** -- `readOnlyHint`, `destructiveHint`, `idempotentHint` so clients can warn before you nuke something
-- **Type-safe schemas** -- Zod v4 validation on every parameter
-- **Lazy config loading** -- validates credentials on first API call, not at startup
-- **Three config sources** -- env vars > config file > Dokploy CLI (first match wins)
-- **Minimal dependencies** -- just `@modelcontextprotocol/sdk`, `zod`, and `@clack/prompts`
-
-## MCP Client Config
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "dokploy": {
-      "command": "npx",
-      "args": ["@vibetools/dokploy-mcp"],
-      "env": {
-        "DOKPLOY_URL": "https://panel.example.com",
-        "DOKPLOY_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
 ```
-
-### Claude Code
-
-Add to `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "dokploy": {
-      "command": "npx",
-      "args": ["@vibetools/dokploy-mcp"],
-      "env": {
-        "DOKPLOY_URL": "https://panel.example.com",
-        "DOKPLOY_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
+search   →  "what can Dokploy do with applications?"
+execute  →  runs a multi-step workflow in one sandboxed call
 ```
 
-### Cursor
+One `execute` call can spin up an app, configure resource limits, set 5 env vars, create 3 file mounts, attach a domain with HTTPS, deploy, wait for it to come up, verify it's running, and clean up after itself. Eight API calls. One context window round-trip. Sub-second sandbox overhead.
 
-Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
+**What this looks like in practice:**
 
-```json
-{
-  "mcpServers": {
-    "dokploy": {
-      "command": "npx",
-      "args": ["@vibetools/dokploy-mcp"],
-      "env": {
-        "DOKPLOY_URL": "https://panel.example.com",
-        "DOKPLOY_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
+| | Old way (endpoint-per-tool) | Code Mode |
+|---|---|---|
+| Tool definitions sent | ~92,354 tokens (377 tools) | ~218 tokens (2 tools) |
+| Deploy workflow (8 API calls) | 8 round-trips through the model | 1 execute call, done |
+| Context window tax | ~738k tokens on tool schemas alone | ~218 tokens total |
 
-### VS Code
+That last row is why this exists. Every token spent on tool definitions is a token your agent can't use for reasoning. We just gave you 738k of them back.
 
-Add to `.vscode/mcp.json`:
+## Configuration
 
-```json
-{
-  "servers": {
-    "dokploy": {
-      "command": "npx",
-      "args": ["@vibetools/dokploy-mcp"],
-      "env": {
-        "DOKPLOY_URL": "https://panel.example.com",
-        "DOKPLOY_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
+| Variable | Required | Description |
+|---|---|---|
+| `DOKPLOY_URL` | Yes | Your Dokploy panel URL |
+| `DOKPLOY_API_KEY` | Yes | API key from Dokploy settings |
+| `DOKPLOY_TIMEOUT` | No | Request timeout in ms (default: `30000`) |
 
-Already ran `setup` or have Dokploy CLI authenticated? Drop the `env` block entirely.
+Resolution order: env vars > `~/.config/dokploy-mcp/config.json` > Dokploy CLI config. First match wins.
 
-## Tools
+<details>
+<summary>Sandbox tuning -- for when the defaults aren't enough drama</summary>
 
-| Module | Tools | Module | Tools |
-|--------|-------|--------|-------|
-| Project | 6 | Deployment | 2 |
-| Application | 26 | Docker | 4 |
-| Compose | 14 | Certificates | 4 |
-| Domain | 8 | Registry | 6 |
-| PostgreSQL | 13 | Destination | 6 |
-| MySQL | 13 | Backup | 8 |
-| MariaDB | 13 | Mounts | 4 |
-| MongoDB | 13 | Port | 4 |
-| Redis | 13 | Redirects | 4 |
-| Security | 4 | Cluster | 4 |
-| Settings | 25 | Admin | 1 |
-| User | 1 | | |
+| Variable | Default | What it does |
+|---|---|---|
+| `DOKPLOY_MCP_SANDBOX_TIMEOUT_MS` | `30000` | How long before the sandbox gives up on your workflow |
+| `DOKPLOY_MCP_SANDBOX_MAX_CALLS` | `25` | Max API calls per execute (prevents runaway loops) |
+| `DOKPLOY_MCP_SANDBOX_MAX_RESULT_BYTES` | `131072` | Max result payload (128 KB) |
+| `DOKPLOY_MCP_SANDBOX_MAX_RESPONSE_BYTES` | `2097152` | Cumulative API response cap (2 MB) |
+| `DOKPLOY_MCP_SANDBOX_RUNTIME` | `subprocess` | `subprocess` (isolated) or `local` (faster, less safe) |
 
-Full reference with parameters and descriptions: **[docs/tools.md](docs/tools.md)**
+</details>
 
-API coverage report: **[docs/coverage.md](docs/coverage.md)**
+## What's in the box
 
-## Configuration
+The Code Mode catalog covers the full Dokploy OpenAPI surface -- 463 procedures across every module. Applications, compose stacks, databases (Postgres, MySQL, MariaDB, MongoDB, Redis), domains, certificates, Docker, servers, backups, notifications, and about 30 more categories you'll discover when you need them.
 
-| Variable | Required | Description |
-|---|---|---|
-| `DOKPLOY_URL` | Yes | Dokploy panel URL -- automatically normalized to `/api/trpc` |
-| `DOKPLOY_API_KEY` | Yes | API key from Dokploy Settings > API |
-| `DOKPLOY_TIMEOUT` | No | Request timeout in ms (default: `30000`) |
+Your agent doesn't need to know any of this upfront. That's the point. It searches when it needs something, executes when it knows what to do.
 
-Resolution order: env vars > `~/.config/dokploy-mcp/config.json` > Dokploy CLI config.
+Coverage details: **[docs/coverage.md](docs/coverage.md)**
 
 ## CLI
 
 ```bash
-npx @vibetools/dokploy-mcp              # Start MCP server (stdio)
-npx @vibetools/dokploy-mcp setup        # Interactive setup wizard (aliases: init, auth)
-npx @vibetools/dokploy-mcp version      # Show version
+npx @vibetools/dokploy-mcp              # Start Code Mode server
+npx @vibetools/dokploy-mcp setup        # Interactive setup
+npx @vibetools/dokploy-mcp version      # Because you'll be asked
 ```
 
 ## Development
 
 ```bash
-git clone https://github.com/vcode-sh/dokploy-mcp.git
-cd dokploy-mcp
+git clone https://github.com/vcode-sh/dokploy-mcp.git && cd dokploy-mcp
 npm install && npm run build
-```
-
-Point your MCP client at the local build:
-
-```json
-{
-  "mcpServers": {
-    "dokploy": {
-      "command": "node",
-      "args": ["/path/to/dokploy-mcp/dist/index.js"],
-      "env": {
-        "DOKPLOY_URL": "https://panel.example.com",
-        "DOKPLOY_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
+npm run typecheck   # TypeScript 6
+npm run lint        # Biome
+npm test            # Vitest
+npm run ci:budgets  # Protocol and runtime budget checks
 ```
 
-```bash
-npm run dev        # Watch mode
-npm run typecheck  # Type-check
-npm run lint       # Lint with Biome
-npm run lint:fix   # Auto-fix
-```
-
-Test with the MCP Inspector:
-
 ```bash
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
-## Standing on the Shoulders of People Who Actually Did the Work
-
-This project is a fork of [Dokploy/mcp](https://github.com/Dokploy/mcp). I rewrote most of it, tripled the tool count, and added things like a setup wizard and config resolution chain -- but "rewrote" is easy when someone else already built the thing you're rewriting.
-
-[Mauricio Siu](https://github.com/Siumauricio) created [Dokploy](https://dokploy.com) itself -- a genuinely impressive open-source PaaS -- and kicked off the MCP server repo. Without Dokploy, there's no API. Without the API, there's no MCP server. Without the MCP server, I'd have had to start from zero instead of "from scratch."
+## Credits
 
-[Henrique Andrade](https://github.com/andradehenrique) did the actual heavy lifting on the original MCP. Projects, applications, PostgreSQL, MySQL, domains -- that was all him. 15 commits, every merged PR. The kind of contributor who doesn't just open issues, he closes them.
+Forked from [Dokploy/mcp](https://github.com/Dokploy/mcp). Started at 67 tools, mass-refactored to 377, then rebuilt the whole thing into an architecture that makes the tool count irrelevant.
 
-And to everyone who opened PRs on the original repo -- merged or not -- your code and ideas shaped what this became:
+[Mauricio Siu](https://github.com/Siumauricio) built [Dokploy](https://dokploy.com) itself -- the PaaS this server talks to. Without the platform, this is a very elaborate way to POST into the void.
 
-[Joshua Macauley](https://github.com/Macawls) · [lucasleal-developer](https://github.com/lucasleal-developer) · [Nour Eddine Hamaidi](https://github.com/HenkDz) · [Corey](https://github.com/limehawk) · [Azil0ne](https://github.com/Azilone)
+[Henrique Andrade](https://github.com/andradehenrique) wrote the original MCP server. 15 commits, every PR merged. The kind of contributor who closes issues instead of opening them.
 
-Unmerged PRs are still blueprints. Someone reads your compose tools PR and thinks "right, I should cover that." Someone sees your consolidation approach and borrows the idea. That's how open source actually works -- not through clean merge histories, but through stolen inspiration with better commit messages.
+Contributors who shaped the original: [Joshua Macauley](https://github.com/Macawls) -- [lucasleal-developer](https://github.com/lucasleal-developer) -- [Nour Eddine Hamaidi](https://github.com/HenkDz) -- [Corey](https://github.com/limehawk) -- [Azil0ne](https://github.com/Azilone)
 
-Cheers to all of you. I owe you mass-produced coffee at minimum.
+Unmerged PRs are still blueprints. That's how open source works -- stolen inspiration with better commit messages.
 
 ## License
 

package/dist/api/client.d.ts

@@ -1,3 +1,5 @@
+import { buildTrpcQueryString } from '../codemode/gateway/request-normalizer.js';
+export declare function unwrapTrpcResponse(data: unknown): unknown;
 export declare class ApiError extends Error {
     readonly status: number;
     readonly statusText: string;
@@ -5,6 +7,7 @@ export declare class ApiError extends Error {
     readonly endpoint: string;
     constructor(status: number, statusText: string, body: unknown, endpoint: string);
 }
+export declare const buildQueryString: typeof buildTrpcQueryString;
 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

@@ -1,5 +1,39 @@
+import { buildTrpcPostBody, buildTrpcQueryString } from '../codemode/gateway/request-normalizer.js';
 import { resolveConfig } from '../config/resolver.js';
 const DEFAULT_TIMEOUT = 30_000;
+function getErrorMessage(body, statusText) {
+    if (typeof body !== 'object' || body === null) {
+        return statusText;
+    }
+    if ('message' in body && typeof body.message === 'string') {
+        return body.message;
+    }
+    if ('error' in body && typeof body.error === 'object' && body.error !== null) {
+        const error = body.error;
+        if ('message' in error && typeof error.message === 'string') {
+            return error.message;
+        }
+        if ('json' in error && typeof error.json === 'object' && error.json !== null) {
+            const json = error.json;
+            if ('message' in json && typeof json.message === 'string') {
+                return json.message;
+            }
+        }
+    }
+    return statusText;
+}
+export function unwrapTrpcResponse(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 getConfig() {
     const resolved = resolveConfig();
     if (!resolved) {
@@ -29,9 +63,7 @@ export class ApiError extends Error {
     body;
     endpoint;
     constructor(status, statusText, body, endpoint) {
-        const msg = typeof body === 'object' && body !== null && 'message' in body
-            ? body.message
-            : statusText;
+        const msg = getErrorMessage(body, statusText);
         super(`Dokploy API error (${status}): ${msg}`);
         this.status = status;
         this.statusText = statusText;
@@ -40,14 +72,7 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-function buildQueryString(body) {
-    if (!body || typeof body !== 'object')
-        return '';
-    const entries = Object.entries(body)
-        .filter(([, v]) => v != null)
-        .map(([k, v]) => [k, String(v)]);
-    return entries.length > 0 ? new URLSearchParams(entries).toString() : '';
-}
+export const buildQueryString = buildTrpcQueryString;
 /**
  * Checks whether an error was caused by an aborted fetch.
  * Both checks are needed: older Node versions throw DOMException,
@@ -70,7 +95,7 @@ async function request(method, path, body) {
                 Accept: 'application/json',
                 'x-api-key': apiKey,
             },
-            body: method === 'POST' && body ? JSON.stringify(body) : undefined,
+            body: method === 'POST' ? buildTrpcPostBody(body) : undefined,
             signal: controller.signal,
         });
         const text = await response.text();
@@ -84,7 +109,7 @@ async function request(method, path, body) {
         if (!response.ok) {
             throw new ApiError(response.status, response.statusText, data, path);
         }
-        return data;
+        return unwrapTrpcResponse(data);
     }
     catch (error) {
         if (error instanceof ApiError) {

package/dist/cli/index.js

@@ -41,6 +41,7 @@ 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)
+  DOKPLOY_MCP_SANDBOX_RUNTIME subprocess or local (default: subprocess)
 
 Documentation:
   https://github.com/vcode-sh/dokploy-mcp