Feature: Onboarding Plugin

Relevant source files

The following files were used as context for generating this wiki page:

• internal/server-plugins/onboarding/plugin.go
• internal/server-plugins/onboarding/module.go
• internal/server/plugin.go
• internal/server-plugin/domain/plugin.go
• internal/server-plugins/app/plugin.go
• internal/server-plugins/core/plugin.go
• README.md

The Onboarding Plugin is a core component of the Dokku MCP server, designed to facilitate discovery and interaction for MCP clients, particularly Large Language Models (LLMs). It acts as a meta-plugin, providing resources that dynamically document the server's capabilities, including all available tools, resources, and prompts from other active plugins. This enables an LLM to understand the available functionalities and construct valid operational plans without prior hardcoded knowledge.

The plugin is always active and does not depend on a specific Dokku plugin being installed. Its primary role is to provide a "map" of the server's features, making the entire system self-describing and easier for automated agents to navigate.

Sources: internal/server-plugins/onboarding/plugin.go:1-30, README.md:10-12

Architecture and Core Components

The Onboarding Plugin is implemented as a standard ServerPlugin. Its architecture is centered around dynamically aggregating information from all other active plugins via a central provider.

Sources: internal/server-plugins/onboarding/plugin.go, internal/server-plugins/onboarding/module.go

OnboardingServerPlugin Struct

The core of the feature is the OnboardingServerPlugin struct. It implements the serverDomain.ServerPlugin interface, which is the standard for all plugins within the Dokku MCP server.

// internal/server-plugins/onboarding/plugin.go:16-19
type OnboardingServerPlugin struct {
	provider mcpserver.ServerPluginProvider
}

A key architectural choice is the use of a mcpserver.ServerPluginProvider. This provider is injected after initial construction to break a potential dependency cycle within the uber/fx dependency injection framework. The SetProvider method facilitates this late injection.

Sources: internal/server-plugins/onboarding/plugin.go:16-24

The following diagram illustrates the relationship between the OnboardingServerPlugin, the interfaces it implements and uses, and an example of another plugin (AppsServerPlugin) it discovers.

Dependency Injection and Initialization

The plugin is registered with the uber/fx dependency injection container in module.go. The module provides the OnboardingServerPlugin as a concrete type and also annotates it to be part of the server_plugins group.

An fx.Invoke function is used to hook into the application's startup lifecycle. During the OnStart event, it calls p.SetProvider(adapter) to inject the ServerPluginProvider, completing the plugin's setup.

// internal/server-plugins/onboarding/module.go:19-27
fx.Invoke(func(lc fx.Lifecycle, logger *slog.Logger, adapter mcpserver.ServerPluginProvider, p *OnboardingServerPlugin) {
    lc.Append(fx.Hook{
        OnStart: func(ctx context.Context) error {
            p.SetProvider(adapter)
            logger.Info("Onboarding plugin initialized")
            return nil
        },
    })
}),

Sources: internal/server-plugins/onboarding/module.go:11-28

Provided Resources

The plugin exposes three key resources under the dokku://onboarding/ URI scheme. These resources are designed to be read by an MCP client to understand how to interact with the server.

URI	Name	Description	MIME Type
dokku://onboarding/quickstart	Quickstart	Start here: overview of tools, prompts, resources, planner, and safe usage	text/markdown
dokku://onboarding/capabilities	Capabilities Index	Index of tools, resources, prompts, with examples and safety notes	application/json
dokku://onboarding/intent-map	Intent Map	Mapping of generic platform intents and synonyms to Dokku tools	application/json

Sources: internal/server-plugins/onboarding/plugin.go:35-56

Quickstart Resource

The dokku://onboarding/quickstart resource provides a human- and LLM-readable Markdown document. It serves as an entry point, offering a high-level overview of what can be done, a basic workflow, and best practices.

The content is static and hardcoded within the handleQuickstartResource function. It includes:

• A list of primary actions (e.g., create_app, deploy_app).
• A copy-paste ready example flow.
• Pointers to other discovery resources.
• Safety and troubleshooting tips.

Sources: internal/server-plugins/onboarding/plugin.go:59-86

Capabilities Index Resource

The dokku://onboarding/capabilities resource is the most powerful discovery mechanism. It dynamically generates a JSON document that inventories all tools, resources, and prompts available from all active plugins on the server.

The process for generating this index is as follows:

1. The handleCapabilitiesIndexResource handler is invoked.
2. It iterates through all ToolProviders registered with the ServerPluginProvider.
3. For each provider, it calls GetTools() and adds the name and description of each tool to the index.
4. It performs a similar iteration for ResourceProviders and PromptProviders.
5. The aggregated data is marshaled into a JSON object and returned.

The following sequence diagram shows the data aggregation flow for the capabilities index.

The resulting JSON has a structure like this:

{
  "tools": [
    {
      "name": "create_app",
      "description": "Create a new Dokku application with validation",
      "examples": []
    }
  ],
  "resources": [
    {
      "uri": "dokku://apps/list",
      "name": "Application List",
      "description": "Complete list of all Dokku applications with status",
      "mime_type": "application/json"
    }
  ],
  "prompts": [
    {
      "plugin": "apps",
      "name": "app_doctor",
      "description": "Comprehensive application health diagnosis and troubleshooting"
    }
  ]
}

Sources: internal/server-plugins/onboarding/plugin.go:91-124

Intent Map Resource

The dokku://onboarding/intent-map resource provides a static JSON mapping that connects common, high-level user intents to specific, executable tools available on the server. This is particularly useful for an LLM to translate a natural language request like "push my code" into the concrete deploy_app tool call.

Each entry in the map includes:

• Synonyms: A list of phrases associated with the intent.
• Tool: The corresponding tool name.
• Params: The parameters the tool expects.

Example from the intent map:

{
  "deploy": {
    "synonyms": [
      "release",
      "ship",
      "publish",
      "roll out",
      "push code"
    ],
    "tool": "deploy_app",
    "params": [
      "app_name",
      "repo_url",
      "git_ref"
    ]
  }
}

Sources: internal/server-plugins/onboarding/plugin.go:126-138

Conclusion

The Onboarding Plugin is a foundational feature of the Dokku MCP server that enables dynamic and intelligent interaction with LLM-based clients. By providing structured, self-describing resources like the quickstart guide, capabilities index, and intent-map, it decouples the client from the server's implementation details. This allows the server to evolve its capabilities by adding or modifying plugins, with clients being able to automatically discover and adapt to these changes.

Sources: internal/server-plugins/onboarding/plugin.go