Feature: Domain Management

Relevant source files

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

• internal/server-plugins/domain/plugin.go
• internal/server-plugins/domain/application/domain_service.go
• internal/server-plugins/domain/infrastructure/dokku_adapter.go
• internal/shared/domain_name.vo.go
• internal/server-plugins/core/domain/entities.go
• internal/server-plugins/app/plugin.go

The Domain Management feature is a server plugin that provides an interface for managing global and application-specific domains within a Dokku instance. It exposes its functionality through the Model Context Protocol (MCP), allowing clients like LLMs to interact with Dokku's domain configuration in a structured and programmatic way. The plugin handles listing, adding, removing, and reporting on domains by wrapping the underlying dokku domains CLI commands.

This module follows a clean, layered architecture to separate concerns. It uses a DomainService for business logic and validation, and a DokkuDomainAdapter for infrastructure-level communication with the Dokku CLI. This ensures that the core logic is decoupled from the specific implementation details of interacting with Dokku.

Architecture

The Domain Management plugin is structured in three primary layers: the Plugin layer, the Application Service layer, and the Infrastructure layer. This separation ensures that MCP-specific logic, business rules, and external system interactions are distinctly managed.

The diagram below illustrates the high-level architectural flow for a typical domain management request.

• Plugin Layer (DomainServerPlugin): The entry point for all MCP requests. It implements the serverDomain.ServerPlugin interface, defining the available tools and resources. It is responsible for parsing MCP requests and forwarding them to the application service.
  Sources: internal/server-plugins/domain/plugin.go:19-27
• Application Layer (DomainService): Contains the core business logic. It orchestrates operations, performs validation on inputs (like domain names), and coordinates with the infrastructure layer to fulfill requests. It is completely independent of the MCP protocol.
  Sources: internal/server-plugins/domain/application/domain_service.go:12-21
• Infrastructure Layer (DokkuDomainAdapter): Implements the domain.DomainRepository interface. This layer is responsible for all communication with the external Dokku system by executing commands via the Dokku CLI client. It also parses the raw text output from the CLI into structured Go types.
  Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go:15-23

Core Components

DomainServerPlugin

This struct is the main component of the plugin, responsible for exposing domain management capabilities over MCP.

• ID: domain
• Name: Dokku Domains
• Description: "Manages global and application-specific domains"
• Responsibilities:
  • Implements the ResourceProvider interface to offer data resources.
  • Implements the ToolProvider interface to offer executable tools.
  • Handles MCP requests, calls the DomainService, and formats the responses.

Sources: internal/server-plugins/domain/plugin.go:31-40

DomainService

The service layer acts as a mediator between the plugin entry point and the infrastructure layer.

• Responsibilities:
  • Orchestrates domain operations like ListGlobalDomains, AddGlobalDomain, etc.
  • Performs business-level validation, such as checking for empty or overly long domain names, before passing data to the repository.
  • Logs significant operations.

Sources: internal/server-plugins/domain/application/domain_service.go:24-81

DokkuDomainAdapter

This adapter is the concrete implementation of the DomainRepository interface, bridging the application to the Dokku CLI.

• Responsibilities:
  • Executes specific Dokku domain commands (e.g., domains:report, domains:add-global).
  • Parses the string output from Dokku commands into structured data models like GlobalDomain and DomainsReport.
  • Maps repository method calls to the corresponding Dokku CLI commands.

Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go:26-31, internal/server-plugins/domain/infrastructure/dokku_adapter.go:101-133

Data Models and Entities

The plugin uses several structured types to represent domain-related information.

DomainName Value Object

A strongly-typed representation of a domain name that enforces validation rules upon creation. This prevents invalid domain formats from propagating through the system.

Validation Rules:

• Cannot be empty.
• Cannot be longer than 253 characters.
• Must match the regex ^[a-zA-Z0-9](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/%5Ba-zA-Z0-9-%5D%7B0%2C61%7D%5Ba-zA-Z0-9%5D)?(\.[a-zA-Z0-9](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/%5Ba-zA-Z0-9-%5D%7B0%2C61%7D%5Ba-zA-Z0-9%5D)?)*$.
• Each label (part between dots) cannot be longer than 63 characters.
• Accepts localhost and IP addresses.

Sources: internal/shared/domain_name.vo.go:14-23, internal/shared/domain_name.vo.go:107-135

DomainsReport and GlobalDomain

These structs model the output of Dokku's domains:report command.

The relationship between these entities is shown below.

• GlobalDomain: Represents a single global domain entry. The AddedAt timestamp is not provided by Dokku and is set to the time of retrieval.
  Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go:53-57
• DomainsReport: A comprehensive report containing a global section and a map of sections for each application.
  Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go:101-108
• DomainsReportSection: A subsection of the report, either for global settings or a specific app, detailing vhosts and proxy settings.
  Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go:109-113

MCP Interface

The feature is exposed to MCP clients through one resource and two tools.

Resources

Resources provide read-only access to data.

URI	Name	Description	MIME Type	Handler
dokku://domains/report	Domains Report	Report of all domains configured in Dokku	application/json	handleDomainsReportResource

Sources: internal/server-plugins/domain/plugin.go:43-51

Tools

Tools provide a way to execute actions or mutations.

Name	Description	Parameters	Handler
list_global_domains	List all global domains	(none)	handleListGlobalDomains
add_global_domain	Add a global domain	domain_name (string, required)	handleAddGlobalDomain

Sources: internal/server-plugins/domain/plugin.go:54-68

Functionality and Flows

Adding a Global Domain

This sequence diagram shows the flow when an MCP client calls the add_global_domain tool.

Generating a Domains Report

The dokku://domains/report resource handler triggers a process to fetch and parse the full domains report from Dokku.

1. The handleDomainsReportResource function in plugin.go is called.
2. It calls domainService.GetDomainsReport().
3. This calls domainRepo.GetDomainsReport() on the DokkuDomainAdapter.
4. The adapter executes the dokku domains:report command.
5. The parseReportLine and parseGlobalDomains helper methods in the adapter process the raw text output line by line.
6. It populates a DomainsReport struct, distinguishing between global settings and per-app sections by looking for =====> headers in the output.
7. The structured DomainsReport object is returned up the call stack, serialized to JSON, and sent to the MCP client.

Sources: internal/server-plugins/domain/plugin.go:70-84, internal/server-plugins/domain/infrastructure/dokku_adapter.go:101-133, internal/server-plugins/domain/infrastructure/dokku_adapter.go:153-171

Dokku Command Mapping

The DokkuDomainAdapter maps its repository methods directly to Dokku CLI commands.

Adapter Method	Dokku Command
ListGlobalDomains	domains:report --global
AddGlobalDomain	domains:add-global <domainName>
RemoveGlobalDomain	domains:remove-global <domainName>
SetGlobalDomains	domains:set-global <domains...>
ClearGlobalDomains	domains:clear-global
GetDomainsReport	domains:report
SetLetsEncryptEmail	letsencrypt:set --global email <email>

Sources: internal/server-plugins/domain/infrastructure/dokku_adapter.go

Conclusion

The Domain Management plugin provides a robust and well-architected interface to Dokku's domain features. By leveraging a layered design, strong typing with value objects, and clear separation of concerns, it exposes complex CLI interactions as simple, validated MCP tools and resources. This abstraction allows higher-level clients and AI agents to safely and effectively manage domains on a Dokku server without needing to understand the intricacies of the underlying command-line interface.