Add comprehensive tool coverage for Dokploy API by limehawk · Pull Request #17 · Dokploy/mcp

limehawk · 2026-01-27T20:13:44Z

Summary

This PR resolves the issue where MCP tools with large/complex schemas fail to execute properly (e.g., compose-update with 43 fields, application-update with 87 fields).

Root Cause

Claude API requires JSON Schema draft-2020-12, but the MCP SDK's default Zod-to-JSON-Schema conversion outputs draft-07, causing schema validation failures.

Fixes

Upgrade to Zod v4 for native z.toJSONSchema() with target: "draft-2020-12" support
Pre-convert schemas before MCP SDK registration to bypass SDK's draft-07 conversion
Normalize response IDs to top level for consistent LLM tool chaining (e.g., data.projectId always accessible)
Fix Zod v4 breaking changes:
- z.record(z.string()) → z.record(z.string(), z.string())
- ZodError.errors → ZodError.issues

Testing

Verified with 8 comprehensive scenarios against a live Dokploy sandbox:

✅ Full application deployment workflow
✅ Database stack setup (PostgreSQL + MySQL)
✅ Docker Compose deployment with YAML
✅ Complex 87-field application updates
✅ Multi-environment setup (prod/staging/dev)
✅ Mounts and port mappings
✅ Git-based deployments
✅ Error handling validation

All scenarios pass with proper cleanup (0 orphaned resources).

API Limitations Documented

Some Dokploy API endpoints don't return IDs on create:

mounts.create, port.create, redirects.create, security.create

These operations succeed but LLMs cannot chain delete/update without querying for IDs first.

🤖 Generated with Claude Code

yoinks-yoinks · 2026-02-02T03:54:34Z

Great work! This comprehensive coverage is exactly what the community needs. Looking forward to seeing this merged!

This PR adds 250+ new MCP tools covering the complete Dokploy API, synced with the official OpenAPI specification. New tool categories: - admin: Server monitoring setup - ai: AI assistant management (create, deploy, suggest) - backup: Database and volume backup management - certificates: SSL certificate management - cluster: Swarm cluster node management - compose: Docker Compose project lifecycle - database: Unified database tools (postgres, mysql, mongo, mariadb, redis) - deployment: Deployment history and process management - destination: Backup destination configuration - docker: Container and config management - environment: Project environment management - git: Git provider and repository integration - mounts: File, bind, and volume mount management - notification: Multi-provider notification setup - organization: Organization and invitation management - port: Port mapping configuration - previewDeployment: Preview deployment management - redirects: URL redirect configuration - registry: Docker registry management - rollback: Deployment rollback functionality - schedule: Scheduled task management - security: Security rule configuration - server: Remote server management - settings: System settings and Traefik configuration - sshKey: SSH key management - stripe: Billing integration - swarm: Docker Swarm node information - user: User and permission management All tools include: - Zod schema validation matching OpenAPI spec - Detailed parameter descriptions for LLM usability - Proper error handling and response formatting

yoinks-yoinks · 2026-02-05T08:55:59Z

Issue in this PR: MCP Tools with Large/Complex Schemas Fail to Execute Properly

Description:
Dokploy MCP tools that return large JSON responses or have complex parameter schemas are experiencing execution failures. This appears to be a schema validation or response size limitation issue in the MCP implementation.

Evidence:

Tools with extensive parameter schemas (like compose-update with multiple complex fields) show inconsistent behavior

Some tools work while others with similar complexity fail

Root Cause:

Potential schema validation timeout for complex parameter sets

Response size limits in MCP protocol handling

JSON parsing issues with deeply nested or large response objects

Reproduction Steps:

Call Dokploy MCP tools with complex schemas (compose-update, application management tools)

Observe inconsistent execution or timeout failures

Compare with simpler tools that work reliably

Proposed Resolution:

Implement response streaming for large JSON payloads

Add schema validation timeouts with configurable limits

Split complex tools into smaller, focused operations

Add response size monitoring and chunking

Impact: Blocks full utilization of Dokploy management capabilities through MCP

Priority: High - affects core functionality

limehawk · 2026-02-05T16:44:51Z

Thank you for testing @yoinks-yoinks I'll look into this and add a commit. This may be a Zod3 vs. Zod4 thing

Replaces 312 individual MCP tools with two: dokploy-api (executes any operation) and dokploy-api-schema (discovers operations and params from OpenAPI spec).

Addresses review findings: adds mongo/mariadb/redis categories, missing gitProvider operations, specifies api-schema output format, corrects error handling as new vs preserved, documents polymorphic endpoint flattening.

6 tasks: create api.ts, apiSchema.ts, rewire server, delete old tools, build/verify, update docs. Fixes from review: proper AxiosError status checking, recursive $ref/allOf schema resolution, depth guard against circular refs.

Auto-detect GET vs POST via static set of known GET operations. LLM only needs to provide operation and params.

…chema - dokploy-api: executes any Dokploy API operation with auto-detected HTTP method (GET/POST) via static operations set - dokploy-api-schema: discovers operation parameters from OpenAPI spec with lazy fetch and in-memory caching - Removes all 33 category directories and toolFactory.ts - Adds index signature to FormattedResponse for MCP SDK compatibility - Reduces tool registration from ~70k tokens to ~2k on launch

Replace 170 lines of hand-maintained static lists with dynamic derivation from the Dokploy OpenAPI spec at startup. Both tools now share a single cached spec fetch via utils/openApiSpec.ts. Also surfaces Dokploy's actual error message on 400 responses instead of swallowing it.

limehawk · 2026-03-11T05:33:39Z

Closing in favor of a new PR with an updated description.

This branch evolved significantly since the original PR:

Started by adding 312 individual tools (what this PR described)
Consolidated into 2 generic tools (dokploy-api + dokploy-api-schema)
Replaced all static configuration with dynamic derivation from Dokploy's live OpenAPI spec

The original description no longer reflects what's being delivered. Opening a fresh PR with the full story.

limehawk · 2026-03-11T06:03:05Z

@yoinks-yoinks check out the new method on PR 25 and test it. Appreciate your feedback.

limehawk marked this pull request as draft January 27, 2026 20:17

limehawk force-pushed the feature/openapi-sync branch from 403ca9e to 09589cc Compare February 2, 2026 17:18

limehawk marked this pull request as ready for review February 2, 2026 17:20

limehawk force-pushed the feature/openapi-sync branch 2 times, most recently from 617d004 to 86bada1 Compare February 5, 2026 18:11

limehawk marked this pull request as draft February 5, 2026 19:55

limehawk added 9 commits March 11, 2026 00:29

Add design spec for single api tool consolidation

1c2ce1d

Replaces 312 individual MCP tools with two: dokploy-api (executes any operation) and dokploy-api-schema (discovers operations and params from OpenAPI spec).

Fix spec: add missing db types, git ops, clarify error handling

dc76d40

Addresses review findings: adds mongo/mariadb/redis categories, missing gitProvider operations, specifies api-schema output format, corrects error handling as new vs preserved, documents polymorphic endpoint flattening.

Add implementation plan for single api tool

de8498f

6 tasks: create api.ts, apiSchema.ts, rewire server, delete old tools, build/verify, update docs. Fixes from review: proper AxiosError status checking, recursive $ref/allOf schema resolution, depth guard against circular refs.

Drop method param from dokploy-api tool

9a8562e

Auto-detect GET vs POST via static set of known GET operations. LLM only needs to provide operation and params.

docs: update TOOLS.md for two-tool architecture

39b6e75

docs: update README for two-tool architecture with dynamic OpenAPI spec

ef2b87d

chore: update .talismanrc for current file checksums

dd68ff5

limehawk force-pushed the feature/openapi-sync branch from 539f7d2 to dd68ff5 Compare March 11, 2026 05:22

limehawk closed this Mar 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add comprehensive tool coverage for Dokploy API#17

Add comprehensive tool coverage for Dokploy API#17
limehawk wants to merge 10 commits intoDokploy:mainfrom
limehawk:feature/openapi-sync

limehawk commented Jan 27, 2026 •

edited

Loading

Uh oh!

yoinks-yoinks commented Feb 2, 2026

Uh oh!

yoinks-yoinks commented Feb 5, 2026

Uh oh!

limehawk commented Feb 5, 2026 •

edited

Loading

Uh oh!

limehawk commented Mar 11, 2026

Uh oh!

limehawk commented Mar 11, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

limehawk commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root Cause

Fixes

Testing

API Limitations Documented

Uh oh!

yoinks-yoinks commented Feb 2, 2026

Uh oh!

yoinks-yoinks commented Feb 5, 2026

Uh oh!

limehawk commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

limehawk commented Mar 11, 2026

Uh oh!

limehawk commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

limehawk commented Jan 27, 2026 •

edited

Loading

limehawk commented Feb 5, 2026 •

edited

Loading

limehawk commented Mar 11, 2026 •

edited

Loading