dokploy-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Dokploy MCP Server — an auto-generated MCP (Model Context Protocol) server that exposes 463 tools from the Dokploy API's OpenAPI specification. It allows Claude to interact with Dokploy for managing projects, applications, databases, Docker Compose stacks, and more.

Commands

# Build (compiles TypeScript + copies openapi-spec.json to dist/)
npm run build

# Run in development with watch mode
npm run dev

# Start production build
npm start

# Clean dist/
npm run clean

Required environment variables:

• DOKPLOY_URL — Dokploy API base URL (e.g., https://your-dokploy.com/api)
• DOKPLOY_API_KEY — API key from Dokploy Settings → API Keys

Optional environment variables:

• REQUEST_TIMEOUT_MS — HTTP request timeout in milliseconds (default: 30000)
• DEBUG — Set to 1 to enable structured JSON debug logging to stderr

Architecture

The server is fully auto-generated from src/openapi-spec.json. You do not hand-write API client code — regenerate tools by updating the spec and rebuilding.

Code Generation Flow

openapi-spec.json
       ↓
tool-generator.ts   — iterates all paths, registers MCP tools
       ↓
schema-converter.ts — converts JSON Schema → Zod schemas at runtime
       ↓
name-mapper.ts      — maps OpenAPI paths (e.g. /compose.deploy) → tool names (dokploy_compose_deploy)
       ↓
api-client.ts       — handles tRPC-style HTTP (GET = query param, POST = JSON body, wrapped responses)

tRPC API Conventions

Dokploy exposes a tRPC OpenAPI layer with non-standard conventions:

• GET requests: Input encoded as ?input={encodeURIComponent(JSON.stringify(params))}
• POST requests: Input sent as JSON body
• Response envelope: { result: { data: { json: <actual_data> } } }
• Error envelope: { error: { json: { message, code, data } } }

All of this is handled in src/services/api-client.ts.