Feature: Core Services
Relevant source files
The following files were used as context for generating this wiki page:The Core Services feature is a foundational plugin within the Dokku MCP server. It is responsible for exposing core Dokku functionalities, such as system status, global configuration, plugin management, SSH keys, and Docker registry management. This plugin does not depend on any specific Dokku plugin and is always active, providing essential information and capabilities to MCP clients.
It serves as the primary interface for understanding the state of the Dokku server itself, aggregating data from various Dokku commands into structured resources. It also provides a tool for server administrators to inspect the dokku-mcp server's own logs.
Sources: internal/server-plugins/core/plugin.go:13-16, 47-51
Architecture
The Core Services feature follows a Domain-Driven Design (DDD) pattern, separating concerns into distinct layers: Plugin, Application, and Infrastructure. This layered architecture ensures that business logic is decoupled from implementation details.
- Plugin (Presentation Layer): The
CoreServerPluginis the entry point. It implements theServerPlugininterface, defines the MCP resources and tools, and handles requests from the MCP server. - Application Layer: The
CoreServiceorchestrates the business logic. It contains the use cases (e.g.,GetServerInfo,ListPlugins) and validates inputs before delegating tasks to the repository interfaces. - Infrastructure Layer: The
DokkuCoreAdapterimplements the repository interfaces defined by the domain. It communicates with the Dokku instance by executing CLI commands via theDokkuClient.
Sources: internal/server-plugins/core/plugin.go:21-36, internal/server-plugins/core/application/core_service.go:13-28, internal/server-plugins/core/infrastructure/dokku_adapter.go:14-20
The diagram below illustrates the architectural layers and the flow of control.
Component Relationships
The main components are instantiated and wired together using dependency injection. The CoreServerPlugin holds an instance of CoreService, which in turn depends on multiple repository interfaces, all implemented by the DokkuCoreAdapter.
MCP Interface
The Core plugin exposes its functionality to MCP clients through a set of resources and tools.
Resources
Resources provide read-only access to structured information about the Dokku server.
| URI | Name | Description | MIME Type |
|---|---|---|---|
dokku://core/server/info | Server Information | Complete server information including system status, plugins, domains, SSH keys, and configuration. | application/json |
dokku://core/plugins | Dokku Plugins | List of all installed Dokku plugins with their status and versions. | application/json |
Sources: internal/server-plugins/core/plugin.go:61-80
Tools
The Core plugin provides a tool for administrative purposes.
get_server_logs
This tool retrieves recent logs from the dokku-mcp server's in-memory ring buffer. It is only exposed if ExposeServerLogs is enabled in the server configuration.
| Parameter | Type | Description |
|---|---|---|
last | number | Number of last lines to return (default 200). |
level | string | Optional filter: debug, info, warn, or error. |
contains | string | Optional substring filter. |
Sources: internal/server-plugins/core/plugin.go:96-121
Data Flow: Fetching Server Info
When a client requests the dokku://core/server/info resource, a sequence of calls is made through the architecture to aggregate data from multiple Dokku commands.
The following sequence diagram shows the interactions involved in fulfilling this request.
Dokku Command Abstraction
To ensure safety and maintainability, the DokkuCoreAdapter does not execute arbitrary strings. Instead, it uses a typed CoreCommand enumeration to map internal calls to specific, validated Dokku CLI commands. This prevents command injection and centralizes the command definitions.
Sources: internal/server-plugins/core/infrastructure/dokku_adapter.go:23-29, internal/dokku-api/client.go:17-50
The following Dokku commands are utilized by the Core Services feature:
| Command Constant | Dokku CLI Command | Purpose |
|---|---|---|
CommandVersion | version | Get Dokku version. |
CommandProxyReport | proxy:report | Report proxy settings. |
CommandSchedulerReport | scheduler:report | Report scheduler settings. |
CommandPluginList | plugin:list | List all installed plugins. |
CommandPluginInstall | plugin:install | Install a new plugin. |
CommandPluginUninstall | plugin:uninstall | Uninstall a plugin. |
CommandPluginEnable | plugin:enable | Enable a disabled plugin. |
CommandPluginDisable | plugin:disable | Disable an enabled plugin. |
CommandPluginUpdate | plugin:update | Update a plugin. |
CommandSSHKeysList | ssh-keys:list | List all SSH keys. |
CommandSSHKeysRemove | ssh-keys:remove | Remove an SSH key. |
CommandRegistryLogout | registry:logout | Log out from a Docker registry. |
CommandGitReport | git:report | Report Git settings. |
CommandProxySet | proxy:set | Set proxy settings. |
CommandSchedulerSet | scheduler:set | Set scheduler settings. |
CommandGitSet | git:set | Set Git settings. |
CommandLogsSet | logs:set | Set logging settings. |
Sources: internal/server-plugins/core/domain/core.commands.go
Key Data Structures
The CoreService and DokkuCoreAdapter work with several domain entities to represent the state of the Dokku server. The primary entity is ServerInfo, which aggregates information from other structures.
ServerInfo Entity Composition
The ServerInfo struct provides a comprehensive snapshot of the server's state.
This diagram shows that a ServerInfo object is composed of a SystemStatus, a GlobalConfiguration, ResourceUsage, and lists of DokkuPlugin and SSHKey entities.
Sources: internal/server-plugins/core/infrastructure/dokku_adapter.go:73-101
Limitations
The infrastructure adapter has some known limitations where direct interaction with the Dokku CLI is required:
- SSH Key Addition: Adding SSH keys is not supported via the API, as it typically requires piping input. The service returns an error suggesting manual addition.
- Registry Login: Similar to SSH keys, logging into a Docker registry is not supported due to the need for interactive password input.
Sources: internal/server-plugins/core/infrastructure/dokku_adapter.go:200-203, 230-233