Developer Tooling

Relevant source files

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

• cmd/depgraph/main.go
• README.md
• CONTRIBUTING.md
• scripts/setup-dev.sh
• scripts/setup-dokku-local.sh
• scripts/cleanup-test-apps.sh
• PHASE1_IMPLEMENTATION.md

The dokku-mcp project is equipped with a comprehensive suite of developer tools designed to streamline the development workflow, ensure code quality, and facilitate local testing. The tooling is primarily orchestrated through a Makefile, which leverages a collection of shell scripts and custom Go programs. These tools manage everything from initial environment setup and local dependency management to automated code quality checks and local Dokku instance management for integration testing.

This approach provides a consistent and reproducible development environment for all contributors. Key components include automated Git hooks for pre-commit checks, scripts for managing a local Docker-based Dokku instance, and utilities for inspecting the application's state and dependencies.

Sources: README.md:200-221, CONTRIBUTING.md:21-29

Development Environment Setup

Setting up a local development environment is a standardized process initiated by a few make commands. This ensures that all developers have the necessary tools and configurations to start contributing quickly.

Sources: README.md:200-215, CONTRIBUTING.md:23-29

Initial Setup Workflow

The primary setup involves two main steps: installing Go-based development tools and configuring Git hooks for automated quality checks.

1. Install Tools: The make install-tools command installs all necessary Go tools required for development, linting, and testing.
2. Setup Environment: The make setup-dev command executes the scripts/setup-dev.sh script. This script configures Git to use the project's local .githooks/ directory and ensures the hook scripts are executable.

This diagram illustrates the setup process for a new developer.

Git Hooks and Code Quality

The project uses a pre-commit Git hook to automatically enforce code quality and style before any code is committed. This is configured by make setup-dev.

The pre-commit hook performs the following actions:

• Auto-formats Go code using goimports/gofmt.
• Runs static analysis with go vet.
• Enforces strong typing rules (e.g., blocks interface{}).
• Runs quick tests on modified packages.

Sources: CONTRIBUTING.md:55-65

This diagram shows the sequence of events during a git commit operation.

Makefile Commands

The Makefile is the central entry point for most development tasks. It provides a set of simple, memorable commands that abstract away more complex underlying operations.

Command	Description
make help	Displays all available Makefile commands.
make install-tools	Installs necessary Go development tools like goimports and golangci-lint.
make setup-dev	Configures the local environment, primarily by setting up Git hooks.
make check	Runs all code quality checks, including linting, formatting, and complexity analysis.
make build	Builds the dokku-mcp server binary into the build/ directory.
make start	Builds and runs the server from source.
make clean	Cleans up build artifacts.
make test	Runs all unit and integration tests and generates an HTML coverage report (coverage.html).
make inspect	Launches the MCP Inspector CLI, a tool for browsing server resources and tools without a full client.
make setup-dokku	Sets up a local Dokku container using Docker Compose. Run once.
make dokku-start	Starts the local Dokku container.
make dokku-stop	Stops the local Dokku container.
make test-integration-local	Runs integration tests against the running local Dokku container.

Sources: README.md:167-170, README.md:208-221, README.md:226-241

Local Dokku Instance for Testing

For development and integration testing, the project provides scripts to manage a local Dokku instance running in Docker. This avoids the need for a dedicated remote Dokku server.

Sources: README.md:152-165

Setup and Configuration

The make setup-dokku command orchestrates the setup of the local instance by running the scripts/setup-dokku-local.sh script. This script performs several key actions:

1. Starts the Dokku Docker container via docker compose up -d.
2. Waits for the Dokku service to become available.
3. Generates a dedicated SSH key pair (.ssh/dokku_mcp_test) for testing if one doesn't exist.
4. Adds the public key to the local Dokku instance using dokku ssh-keys:add.
5. Updates the user's local ~/.ssh/config with an entry for dokku.local to simplify SSH connections.
6. Creates a config.yaml file in the project root, pre-configured to connect to the local Dokku instance.

This diagram outlines the flow of the local Dokku setup script.

Test Application Cleanup

To maintain a clean state between test runs, the scripts/cleanup-test-apps.sh script is provided. It removes any test applications (those with dokku-mcp-test in their name) and cleans up the test SSH keys from both the local Dokku instance and the developer's machine.

Sources: scripts/cleanup-test-apps.sh

Custom Go Tools

The project includes custom Go programs located in the cmd/ directory to aid in development and analysis.

Dependency Graph Generator

The tool at cmd/depgraph/main.go is a utility that generates a dependency graph of all internal packages in the project. It outputs the graph in the DOT language, which can be visualized using tools like Graphviz.

The process is as follows:

1. List all packages within the current Go module (go list ./...).
2. For each package, list its imported packages.
3. Filter the imports to include only those that are part of the current module.
4. Print the relationships in DOT format ("package_a" -> "package_b").

This is useful for understanding the internal architecture and identifying potential circular dependencies.

// cmd/depgraph/main.go:19:25
// Build a map of package -> imports
deps := make(map[string][]string)
for _, pkg := range pkgs {
    // ...
    // Only keep imports that are in our module
    for _, imp := range imports {
        for _, p := range pkgs {
            if imp == p {
                deps[pkg] = append(deps[pkg], imp)
            }
        }
    }
}

Sources: cmd/depgraph/main.go

MCP Inspector

The make inspect command provides a quick way to interact with the dokku-mcp server without needing a full MCP client like Cursor or Claude. It builds the binary, launches the MCP Inspector CLI, and connects it to the server in stdio mode. The inspector provides a local URL to a web interface where developers can browse available resources, prompts, and tools, and even make ad-hoc calls to test functionality.

Sources: README.md:46-51

Summary

The developer tooling for dokku-mcp establishes a robust and efficient workflow centered around make and supporting scripts. It automates environment setup, enforces code quality through pre-commit hooks, and simplifies integration testing with a manageable local Dokku instance. Custom Go tools for dependency analysis and an interactive MCP inspector further enhance the developer experience, enabling contributors to build, test, and analyze the project with confidence and consistency.

Sources: README.md, CONTRIBUTING.md