{"_id":"@bakhshb/dokploy-mcp","_rev":"3-4f1a07e93bab3f7baa36dd0a562d5b02","name":"@bakhshb/dokploy-mcp","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@bakhshb/dokploy-mcp","version":"1.0.0","keywords":["modelcontextprotocol","mcp","dokploy"],"author":{"name":"Baraa Bakhsh"},"license":"Apache-2.0","_id":"@bakhshb/dokploy-mcp@1.0.0","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"homepage":"https://github.com/limehawk/dokploy-mcp/tree/feature/openapi-sync","bugs":{"url":"https://github.com/limehawk/dokploy-mcp/issues"},"bin":{"dokploy-mcp":"build/index.js"},"dist":{"shasum":"683538dbcb0c24d9b5bfd43b7de629c3d35683e0","tarball":"https://registry.npmjs.org/@bakhshb/dokploy-mcp/-/dokploy-mcp-1.0.0.tgz","fileCount":15,"integrity":"sha512-xcexYTlmOiy6SFbIProG5cRI3tJj0rj1plw3olEAzC4IHGbBi9qIgIYqZY+MM1n22r1rmwG+kZxuKCODP7MPXA==","signatures":[{"sig":"MEUCICK3Batw/KSpUg1YUPxrMw/ratnGA1O8qVoH1h77RZFIAiEArRUZKtkrUixyrYNReX/U3hVkHeI2VR3DpU0COmvRUfU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51111},"main":"build/index.js","type":"module","gitHead":"1d887ead7a9bef8c7119b763f22739771d3af499","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","format":"prettier --write src/**/*.{ts,js,json}","dev:sse":"npm run build && npm run start:sse","dev:http":"npm run build && npm run start:http","lint:fix":"eslint src/**/*.ts --fix","precommit":"npm run lint && npm run format:check && npm run type-check","start:sse":"node build/index.js --sse","start:http":"node build/index.js --http","type-check":"tsc --noEmit","start:stdio":"node build/index.js","format:check":"prettier --check src/**/*.{ts,js,json}"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"repository":{"url":"git+https://github.com/bakhshb/dokploy-mcp.git","type":"git"},"_npmVersion":"10.9.7","description":"MCP Server for Dokploy API (fork of @ahdev/dokploy-mcp)","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","axios":"^1.9.0","express":"^5.1.0","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.27.0","prettier":"^3.5.3","typescript":"^5.8.3","@types/node":"^22.15.21","@types/eslint":"^9.6.1","@types/express":"^5.0.2","eslint-config-prettier":"^10.1.5","eslint-plugin-prettier":"^5.4.1","@typescript-eslint/parser":"^8.32.1","@typescript-eslint/eslint-plugin":"^8.32.1"},"_npmOperationalInternal":{"tmp":"tmp/dokploy-mcp_1.0.0_1774890536301_0.3999959143084344","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bakhshb/dokploy-mcp","version":"1.0.1","keywords":["modelcontextprotocol","mcp","dokploy"],"author":{"name":"Baraa Bakhsh"},"license":"Apache-2.0","_id":"@bakhshb/dokploy-mcp@1.0.1","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"homepage":"https://github.com/limehawk/dokploy-mcp/tree/feature/openapi-sync","bugs":{"url":"https://github.com/limehawk/dokploy-mcp/issues"},"bin":{"dokploy-mcp":"build/index.js"},"dist":{"shasum":"d26452aebc953f470cb787f163473c74da507190","tarball":"https://registry.npmjs.org/@bakhshb/dokploy-mcp/-/dokploy-mcp-1.0.1.tgz","fileCount":15,"integrity":"sha512-eEz0RCRYEz8NB4LmOEDw73YeLFeegCzQeiIiZ9utEl1mu3vv9rC3cdwVyHwkNzJjq414rVsx8Tjc6T9Bwy74uQ==","signatures":[{"sig":"MEUCIBHrlWWq0ALSPCcZGNrwJYk0E2pvkIf4mqR2TNpb1bYpAiEA3bPZFR39bAUfquxKXp83lCi157njbjTVUL/YHLplA0g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51232},"main":"build/index.js","type":"module","gitHead":"df6e4fb4dd99d1ec61ccd6536d4e86e474d65a1b","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","format":"prettier --write src/**/*.{ts,js,json}","dev:sse":"npm run build && npm run start:sse","dev:http":"npm run build && npm run start:http","lint:fix":"eslint src/**/*.ts --fix","precommit":"npm run lint && npm run format:check && npm run type-check","start:sse":"node build/index.js --sse","start:http":"node build/index.js --http","type-check":"tsc --noEmit","start:stdio":"node build/index.js","format:check":"prettier --check src/**/*.{ts,js,json}"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"repository":{"url":"git+https://github.com/bakhshb/dokploy-mcp.git","type":"git"},"_npmVersion":"10.9.7","description":"MCP Server for Dokploy API (fork of @ahdev/dokploy-mcp)","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","axios":"^1.9.0","express":"^5.1.0","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.27.0","prettier":"^3.5.3","typescript":"^5.8.3","@types/node":"^22.15.21","@types/eslint":"^9.6.1","@types/express":"^5.0.2","eslint-config-prettier":"^10.1.5","eslint-plugin-prettier":"^5.4.1","@typescript-eslint/parser":"^8.32.1","@typescript-eslint/eslint-plugin":"^8.32.1"},"_npmOperationalInternal":{"tmp":"tmp/dokploy-mcp_1.0.1_1774897611627_0.5132855854277392","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bakhshb/dokploy-mcp","version":"1.0.2","description":"MCP Server for Dokploy API (fork of @ahdev/dokploy-mcp)","main":"build/index.js","bin":{"dokploy-mcp":"build/index.js"},"scripts":{"build":"npm run clean && tsc && chmod 755 build/index.js","dev":"tsc --watch","start:stdio":"node build/index.js","start:http":"node build/index.js --http","start:sse":"node build/index.js --sse","dev:http":"npm run build && npm run start:http","dev:sse":"npm run build && npm run start:sse","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","format":"prettier --write src/**/*.{ts,js,json}","format:check":"prettier --check src/**/*.{ts,js,json}","type-check":"tsc --noEmit","clean":"rm -rf build","precommit":"npm run lint && npm run format:check && npm run type-check","test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"git+https://github.com/bakhshb/dokploy-mcp.git"},"keywords":["modelcontextprotocol","mcp","dokploy"],"author":{"name":"Baraa Bakhsh"},"bugs":{"url":"https://github.com/limehawk/dokploy-mcp/issues"},"homepage":"https://github.com/limehawk/dokploy-mcp/tree/feature/openapi-sync","license":"Apache-2.0","type":"module","dependencies":{"@modelcontextprotocol/sdk":"1.12.0","axios":"^1.9.0","express":"^5.1.0","zod":"3.25.28"},"devDependencies":{"@types/eslint":"^9.6.1","@types/express":"^5.0.2","@types/node":"^22.15.21","@typescript-eslint/eslint-plugin":"^8.32.1","@typescript-eslint/parser":"^8.32.1","eslint":"^9.27.0","eslint-config-prettier":"^10.1.5","eslint-plugin-prettier":"^5.4.1","prettier":"^3.5.3","typescript":"^5.8.3"},"_id":"@bakhshb/dokploy-mcp@1.0.2","gitHead":"0d79751ec528c48dcb7e66d4d52cf720fb4382f8","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-faU+oH+wvvXc5KDdUaXgWSKW2FBe1YEWsS+mNZiX/lpANLgP3dqzye9DUEuOc8euLuhEzTc1hcJbxlch/EGvSA==","shasum":"d9b32c6fba569af85d195f612e74cc6d0cd8fe19","tarball":"https://registry.npmjs.org/@bakhshb/dokploy-mcp/-/dokploy-mcp-1.0.2.tgz","fileCount":15,"unpackedSize":51258,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDt7ddCfUvyc0BUDT4g+73yYIIbskvYs+7WBa+ploVTMgIhAIlGwFDY1XkaQcz7YawIFwfp0SvwIwDqxjmMHAvI5CM5"}]},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"directories":{},"maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dokploy-mcp_1.0.2_1774897941454_0.6932308803677691"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T17:08:56.193Z","modified":"2026-03-30T19:12:21.718Z","1.0.0":"2026-03-30T17:08:56.489Z","1.0.1":"2026-03-30T19:06:51.785Z","1.0.2":"2026-03-30T19:12:21.606Z"},"bugs":{"url":"https://github.com/limehawk/dokploy-mcp/issues"},"author":{"name":"Baraa Bakhsh"},"license":"Apache-2.0","homepage":"https://github.com/limehawk/dokploy-mcp/tree/feature/openapi-sync","keywords":["modelcontextprotocol","mcp","dokploy"],"repository":{"type":"git","url":"git+https://github.com/bakhshb/dokploy-mcp.git"},"description":"MCP Server for Dokploy API (fork of @ahdev/dokploy-mcp)","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"readme":"# Dokploy MCP Server\n\n**Fork of [limehawk/dokploy-mcp](https://github.com/limehawk/dokploy-mcp/tree/feature/openapi-sync) - Original work by limehawk**\n\n[![npm version](https://img.shields.io/npm/v/@bakhshb/dokploy-mcp.svg)](https://www.npmjs.com/package/@bakhshb/dokploy-mcp) [<img alt=\"Install in VS Code (npx)\" src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Dokploy%20MCP&color=0098FF\">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n\nDokploy MCP Server exposes Dokploy functionalities as tools consumable via the Model Context Protocol (MCP). It allows MCP-compatible clients (e.g., AI models, other applications) to interact with your Dokploy server programmatically.\n\nThis server focuses exclusively on **tools** for direct Dokploy API operations, providing a clean and efficient interface for project and application management.\n\n## 🛠️ Getting Started\n\n### Requirements\n\n- Node.js >= v18.0.0 (or Docker)\n- Cursor, VS Code, Claude Desktop, or another MCP Client\n- A running Dokploy server instance\n\n### Install in Cursor\n\nGo to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`\n\nAdd this to your Cursor `~/.cursor/mcp.json` file. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n<details>\n<summary>Alternative: Use Bun</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Alternative: Use Deno</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"deno\",\n      \"args\": [\"run\", \"--allow-env\", \"--allow-net\", \"npm:@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n### Install in Windsurf\n\nAdd this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in VS Code\n\n[<img alt=\"Install in VS Code (npx)\" src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Dokploy%20MCP&color=0098FF\">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n[<img alt=\"Install in VS Code Insiders (npx)\" src=\"https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Dokploy%20MCP&color=24bfa5\">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)\n\nAdd this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n```json\n{\n  \"servers\": {\n    \"dokploy-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in Zed\n\nAdd this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.\n\n```json\n{\n  \"context_servers\": {\n    \"dokploy-mcp\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"]\n      },\n      \"settings\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in Claude Desktop\n\nAdd this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Install in BoltAI\n\nOpen the \"Settings\" page of the app, navigate to \"Plugins,\" and enter the following JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Using Docker\n\nThe Docker container supports both **stdio** and **HTTP** transport modes, making it flexible for different deployment scenarios.\n\n1.  **Build the Docker Image:**\n\n    ```bash\n    git clone https://github.com/Dokploy/mcp.git\n    cd dokploy-mcp\n    docker build -t dokploy-mcp .\n    ```\n\n2.  **Manual Docker Commands:**\n\n    **Stdio Mode (for MCP clients):**\n\n    ```bash\n    docker run -it --rm \\\n      -e DOKPLOY_URL=https://your-dokploy-server.com/api \\\n      -e DOKPLOY_API_KEY=your_token_here \\\n      dokploy-mcp\n    ```\n\n    **HTTP Mode (for web applications):**\n\n    ```bash\n    docker run -it --rm \\\n      -p 8080:3000 \\\n      -e MCP_TRANSPORT=http \\\n      -e DOKPLOY_URL=https://your-dokploy-server.com/api \\\n      -e DOKPLOY_API_KEY=your_token_here \\\n      dokploy-mcp\n    ```\n\n3.  **Docker Compose:**\n\n    Use the provided `docker-compose.yml` for production deployments:\n\n    ```bash\n    # Start HTTP service\n    docker-compose up -d dokploy-mcp-http\n\n    # View logs\n    docker-compose logs -f dokploy-mcp-http\n    ```\n\n4.  **MCP Client Configuration:**\n\n    **For stdio mode (Claude Desktop, VS Code, etc.):**\n\n    ```json\n    {\n      \"mcpServers\": {\n        \"dokploy-mcp\": {\n          \"command\": \"docker\",\n          \"args\": [\n            \"run\",\n            \"-i\",\n            \"--rm\",\n            \"-e\",\n            \"DOKPLOY_URL=https://your-dokploy-server.com/api\",\n            \"-e\",\n            \"DOKPLOY_API_KEY=your_token_here\",\n            \"dokploy-mcp\"\n          ]\n        }\n      }\n    }\n    ```\n\n    **For HTTP mode (web applications):**\n\n    Start the HTTP server first, then configure your client to connect to `http://localhost:3000/mcp`.\n\n### Install in Windows\n\nThe configuration on Windows is slightly different compared to Linux or macOS. Use `cmd` as the command wrapper:\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"@bakhshb/dokploy-mcp\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\n- `DOKPLOY_URL`: Your Dokploy server API URL (required) — **must include `/api` at the end**, e.g., `http://192.168.100.100:3000/api` or `https://your-dokploy-server.com/api`\n- `DOKPLOY_API_KEY`: Your Dokploy API authentication token (required)\n\n## 🚀 Transport Modes\n\nThis MCP server supports multiple transport modes to suit different use cases:\n\n### Stdio Mode (Default)\n\nThe default mode uses stdio for direct process communication, ideal for desktop applications and command-line usage.\n\n```bash\n# Run with stdio (default)\nnpx -y @bakhshb/dokploy-mcp\n# or\nnpm run start:stdio\n```\n\n### HTTP Mode (Streamable HTTP + Legacy SSE)\n\nModern HTTP mode exposes the server via HTTP/HTTPS supporting **both modern and legacy protocols** for maximum compatibility:\n\n- **Streamable HTTP (MCP 2025-03-26)** - Modern protocol with session management\n- **Legacy SSE (MCP 2024-11-05)** - Backwards compatibility for older clients\n\n```bash\n# Run with HTTP mode\nnpm run start:http\n# or\nnpx -y @bakhshb/dokploy-mcp --http\n# or via environment variable\nMCP_TRANSPORT=http npx -y @bakhshb/dokploy-mcp\n```\n\n**Modern Streamable HTTP Endpoints:**\n\n- **POST /mcp** - Client-to-server requests\n- **GET /mcp** - Server-to-client notifications\n- **DELETE /mcp** - Session termination\n- **GET /health** - Health check endpoint\n\n**Legacy SSE Endpoints (Backwards Compatibility):**\n\n- **GET /sse** - SSE stream initialization\n- **POST /messages** - Client message posting\n\n**Configuration:**\n\n- Internal port: `3000` (fixed)\n- External port: configurable via `EXTERNAL_PORT` (default: `3000`)\n- Supports both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05)\n- Session management with automatic cleanup for both transport types\n\n**Client Compatibility:**\n\nModern clients automatically use the Streamable HTTP endpoints, while legacy clients can connect using the SSE endpoints. The server handles both protocols simultaneously, ensuring compatibility with:\n\n- **Modern MCP clients** (Claude Desktop, Cline, etc.) → Use `/mcp` endpoints\n- **Legacy MCP clients** → Use `/sse` and `/messages` endpoints\n- **Custom integrations** → Choose the appropriate protocol for your needs\n\nFor detailed transport mode documentation and client examples, refer to the configuration examples above.\n\n## 📚 Available Tools\n\nThis MCP server exposes **2 tools** that provide full coverage of the entire Dokploy API (300+ operations):\n\n### `dokploy-api` — Execute any Dokploy API operation\n\nA single, generic tool that can call any Dokploy API endpoint. The HTTP method (GET/POST) is **auto-detected from the live OpenAPI spec** — no static configuration to maintain.\n\n```json\n{ \"operation\": \"application.create\", \"params\": { \"name\": \"my-app\", \"projectId\": \"...\" } }\n{ \"operation\": \"project.all\" }\n{ \"operation\": \"settings.health\" }\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `operation` | string | Yes | API operation path, e.g. `\"application.create\"`, `\"server.one\"` |\n| `params` | object | No | Parameters — sent as JSON body (POST) or query string (GET) |\n\n### `dokploy-api-schema` — Discover operations and parameters\n\nIntrospects the Dokploy OpenAPI spec to list available categories, operations, and their full parameter schemas. Call with no params for a category overview, with `category` to list operations, or with `operation` for full parameter details.\n\n```json\n{}                                          // → list all categories\n{ \"category\": \"application\" }               // → list operations in category\n{ \"operation\": \"application.create\" }       // → full parameter schema\n```\n\n### Why 2 tools instead of 300+?\n\nPrevious versions registered a separate MCP tool for every API endpoint. This created maintenance overhead — every Dokploy update required manually adding new tools. The current architecture derives everything from the live OpenAPI spec at startup:\n\n- **Zero maintenance**: New Dokploy API endpoints are available automatically\n- **Accurate method detection**: GET vs POST determined from the spec, not a static list\n- **Rich discovery**: The schema tool resolves `$ref`, `allOf`, `oneOf` so AI clients get complete parameter information\n- **Full coverage**: Every operation Dokploy exposes is accessible, not just a curated subset\n\n**Tool Annotations:** Both tools include semantic annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) to help MCP clients understand their behavior.\n\nFor detailed documentation, see **[TOOLS.md](TOOLS.md)**.\n\n## 🏗️ Architecture\n\nBuilt with **@modelcontextprotocol/sdk**, **TypeScript**, and **Zod** for type-safe schema validation:\n\n- **2 Tools, Full API Coverage**: A generic executor + schema discovery tool covering 300+ Dokploy operations\n- **Dynamic OpenAPI Spec Derivation**: GET/POST method detection, operation lists, and parameter schemas are all derived from the live Dokploy OpenAPI spec at startup — cached after first fetch\n- **Multiple Transports**: Stdio (default) and HTTP (Streamable HTTP + legacy SSE)\n- **Structured Error Handling**: Status-specific error messages (400/401/403/404/422/5xx) that surface Dokploy's actual validation details\n- **Type Safety**: Full TypeScript support with Zod schema validation\n- **Tool Annotations**: Semantic hints for MCP client behavior understanding\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `src/mcp/tools/api.ts` | Generic API executor — routes any operation to the correct endpoint |\n| `src/mcp/tools/apiSchema.ts` | Schema discovery — resolves `$ref`, `allOf`, `oneOf` from OpenAPI spec |\n| `src/utils/openApiSpec.ts` | Shared OpenAPI spec cache — single fetch, used by both tools |\n| `src/server.ts` | MCP server setup and tool registration |\n| `src/http-server.ts` | Express server with Streamable HTTP + legacy SSE transport |\n\n## 🔧 Development\n\nClone the project and install dependencies:\n\n```bash\ngit clone https://github.com/Dokploy/mcp.git\ncd dokploy-mcp\nnpm install\n```\n\nBuild:\n\n```bash\nnpm run build\n```\n\n### Local Configuration Example\n\n```json\n{\n  \"mcpServers\": {\n    \"dokploy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/path/to/dokploy-mcp/src/index.ts\"],\n      \"env\": {\n        \"DOKPLOY_URL\": \"https://your-dokploy-server.com/api\",\n        \"DOKPLOY_API_KEY\": \"your-dokploy-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpx -y @modelcontextprotocol/inspector npx @bakhshb/dokploy-mcp\n```\n\n### Documentation\n\n- **[TOOLS.md](TOOLS.md)** - Complete tool reference with schemas and examples\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contributing guidelines\n\n## 🔧 Troubleshooting\n\n### MCP Client Errors\n\n1. Try adding `@latest` to the package name.\n\n2. Make sure you are using Node v18 or higher to have native fetch support with `npx`.\n\n3. Verify your `DOKPLOY_URL` and `DOKPLOY_API_KEY` environment variables are correctly set.\n\n## 🤝 Contributing\n\nWe welcome contributions! If you'd like to contribute to the Dokploy MCP Server, please check out our [Contributing Guide](CONTRIBUTING.md).\n\n## 🆘 Support\n\nIf you encounter any issues, have questions, or want to suggest a feature, please [open an issue](https://github.com/Dokploy/mcp/issues) in our GitHub repository.\n\n## 📄 License\n\nThis project is licensed under the [Apache License](LICENSE).\n","readmeFilename":"README.md"}