Contributing

Welcome! We’re glad you want to contribute. This page is a quick orientation — detailed guides are linked below.

Quick Start

1. Clone and build:

   git clone https://github.com/jmrplens/portainer-mcp-enhanced.git
   cd portainer-mcp-enhanced
   make build          # → dist/portainer-mcp-enhanced

2. Run tests:

   make test           # Unit tests
   make test-all       # Unit + integration (requires Docker)

3. Format and lint:

   gofmt -s -w .
   go vet ./...

Developer Guides

Project Structure File layout, layer diagram, and key source files

Development Workflow Setup, build, test, debug, and release

Adding Tools Step-by-step guide from YAML definition to meta-tool integration

Testing Guide Unit tests, integration tests, mocking, and coverage

Dependencies & Toolchain Go modules, build tools, and CI/CD infrastructure

CI/CD & Releases GitHub Actions, GoReleaser, Docker images

Key Conventions

Area	Convention
Naming	PascalCase exported, camelCase private
Errors	fmt.Errorf("context: %w", err) — always wrap with context
Imports	Standard lib → external → internal (blank line separated)
Tests	Table-driven with descriptive case names
Models	Raw SDK → Local models (never expose raw to handlers)
Logging	zerolog to stderr; never log to stdout (MCP transport)
Commits	Conventional Commits — feat:, fix:, docs:, etc.

Pull Request Process

1. Fork and create a branch: feat/my-feature or fix/my-fix
2. Implement with tests
3. Verify: go build ./... && go vet ./... && make test-all
4. Submit with a clear title and description

Tip

See the full CONTRIBUTING.md for the complete checklist and guidelines.

Architecture Reference

Architecture Server layers, client model, tool registration

Clients & Models Two-layer model architecture and conventions

Design Decisions Architectural records and decision log

Security

Report vulnerabilities privately — see the Security Policy for details.