Dokploy / Dokploy/mcp

Progressive tool disclosure: start on a small preset, load more tags on demand via tools/list_changed

Open
#81 3 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
379
Forks
77
PR merge metrics
No merged PRs in 30d

Description

Follow-up to #52, which was closed by #51 (presets + tag filters). Presets solved the static half of the problem; the dynamic half is still open.

Problem

DOKPLOY_TOOL_PRESET / DOKPLOY_ENABLED_TAGS are read once, at process start, from env. That makes preset selection a bet placed before the session on what the session will need.

In practice a Dokploy session is ~95% application-deploy, deployment-readLogs, docker-*. Then once in a while you need backup-* or mysql-* — and the only way to get there is to edit .mcp.json and restart the MCP client, which in Claude Code (and most agent clients) means losing the accumulated session context. So users don't pick minimal; they pick a wide tag list "just in case" and pay for it in every session.

Measured on my install with DOKPLOY_ENABLED_TAGS covering 11 tags:

  • 162 tools registered
  • ~8 KB of tool names alone ≈ 2.3k tokens of context, before a single schema is fetched
  • a project with two Dokploy instances configured = 324 tools

Proposal: progressive disclosure

  1. Declare capabilities.tools.listChanged = true.
  2. Ship one always-present meta-tool, e.g. dokploy_load_tools(tags: string[]), that registers the requested tag groups at runtime and emits notifications/tools/list_changed.
  3. With escalation available, the default can safely become minimal (or even core) instead of all.

The agent then starts with ~20 tools, and the moment it actually needs backups it calls dokploy_load_tools(["backup"]) and continues in the same session.

Clients do handle this: Claude Code re-reads the tool list mid-session — I watched a server drop and rejoin between two turns and the available-tools list was rebuilt without a restart.

Why it pairs well with #46

#46 asks for a read-only mode. Progressive disclosure is the same mechanism from the other end: start on a read-only profile, escalate to mutating tools explicitly. One implementation covers both requests.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing preset and tag-filter implementation from #52/#51 and the current MCP capability and tool-registration entry points. Trace how DOKPLOY_TOOL_PRESET and DOKPLOY_ENABLED_TAGS are loaded, then define the runtime loading and tools/list_changed behavior. Done means a minimal default can load additional tag groups in-session without a restart while advertising the capability.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.