fix(secret): fail fast when Docker Desktop is not available

[Pnkcaht]

What I did

Introduced explicit environment validation and hardened secret handling in the secret package to ensure docker mcp secret set behaves correctly depending on the runtime environment.

This change clarifies the distinction between Docker Desktop and headless Docker Engine environments, failing fast when Desktop-only secret backends are unavailable. It also improves secret parsing, provider validation, and secure STDIN-based value ingestion, reducing ambiguity and preventing partially executed flows.

The implementation wires environment detection through the Docker CLI initialization path and centralizes provider semantics, ensuring clearer errors and safer secret management.

Related issue

Fixed #355

What was the problem ?

The docker mcp secret set command could be executed in environments where Docker Desktop services are not available (e.g. Docker Engine / CE).

In these cases:

• The command initialized successfully
• Execution proceeded into Desktop-dependent logic
• Failures occurred late in the flow
• Error messages did not clearly explain that Docker Desktop was required

This resulted in confusing behavior where the command appeared broken instead of explicitly unsupported.

Diagram

Secret Set Execution & Environment Validation Flow

flowchart TD
    A[User runs docker mcp secret set] --> B[Parse provider & secret input]
    B --> C[Initialize Docker CLI]
    C --> D{Running on Docker Desktop?}
    D -->|Yes| E[Set secret via Desktop / JFS backend]
    D -->|No| F[Fail fast with clear error]

Loading

Explanation

The diagram illustrates the new execution flow for docker mcp secret set:

Input Handling

The command first parses secret input, supporting both key=value syntax and secure STDIN-based ingestion depending on the selected provider.

Environment Detection

After initializing the Docker CLI, the runtime environment is explicitly checked to determine whether Docker Desktop services are available.

Fail-Fast Behavior

If the command is executed on Docker Engine (headless / CE), execution stops immediately with a clear, actionable error message.

Desktop Path

When Docker Desktop is available, the secret is safely stored using the Desktop-backed secrets client.

This ensures unsupported environments are rejected early, while supported environments follow the normal happy path.

Before

• No explicit validation of Docker Desktop availability
• Command executed partially in unsupported environments
• Errors surfaced late and without clear guidance
• Users had no indication that Docker Desktop was required

After

• Runtime environment is validated early
• Headless Docker Engine is detected explicitly
• Unsupported environments fail fast with actionable errors
• Desktop environments continue to work unchanged
• Secret parsing and provider semantics are clearer and safer

Testing

This change was validated through local builds and code review.
No new automated tests were added as part of this PR, since the behavior depends on runtime environment detection (Docker Desktop vs. headless Docker Engine) and would require environment-specific integration coverage.
Follow-up work may introduce targeted integration tests once a suitable test harness for Docker Desktop–dependent behavior is available.

[cutecatfann]

LGTM!

[Pnkcaht]

I resolved the Github Lint and Windows errors. @cutecatfann

[cutecatfann]

Looks like you have one more linting rule that still is not passing:

cmd/docker-mcp/secret-management/secret/set.go:116:10: ST1005: error strings should not be capitalized (staticcheck)
#16 88.83 		return fmt.Errorf(

Let me know when you fix it and I can retrigger the run :)

Thanks for contributing!

[Pnkcaht]

@cutecatfann I checked locally here, it was a "." that I hadn't removed, now I think it's gone, thank you. :)
I'll continue reviewing the issues here to clean them up; if there's anything specific that needs help, just let me know.

[cutecatfann]

Appreciate it @Pnkcaht ! I retriggered the build for you as well :)

[Pnkcaht]

@cutecatfann It was another one related to the import, I've already fixed it, now it will work. 🤣

[Pnkcaht]

A new error appeared in Lint; it was a capital D and a long message that shortened. I hope it goes away now. @cutecatfann sorry for this, Github Lint is very demanding.

Build Lint Finished

pnkcaht@pnkcaht:~/Documents/MCPgateway/mcp-gateway$ make lint-linux
docker buildx build --build-arg GO_LDFLAGS --build-arg DOCKER_MCP_PLUGIN_BINARY --target=lint --platform=linux .
[+] Building 92.7s (14/14) FINISHED                                                                                              docker:default
 => [internal] load build definition from Dockerfile                                                                                       0.0s
 => => transferring dockerfile: 5.40kB                                                                                                     0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile:1                                                                  1.3s
 => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:b6afd42430b15f2d2a4c5a02b919e98a525b785b1aaff16747d2f623364e39b6            0.0s
 => => resolve docker.io/docker/dockerfile:1@sha256:b6afd42430b15f2d2a4c5a02b919e98a525b785b1aaff16747d2f623364e39b6                       0.0s
 => [internal] load metadata for docker.io/golangci/golangci-lint:v2.8.0-alpine                                                            0.8s
 => [internal] load metadata for docker.io/library/golang:1.25.5-alpine                                                                    0.9s
 => [internal] load .dockerignore                                                                                                          0.0s
 => => transferring context: 199B                                                                                                          0.0s
 => [internal] load build context                                                                                                          0.6s
 => => transferring context: 1.58MB                                                                                                        0.6s
 => [base 1/3] FROM docker.io/library/golang:1.25.5-alpine@sha256:ac09a5f469f307e5da71e766b0bd59c9c49ea460a528cc3e6686513d64a6f1fb         0.0s
 => => resolve docker.io/library/golang:1.25.5-alpine@sha256:ac09a5f469f307e5da71e766b0bd59c9c49ea460a528cc3e6686513d64a6f1fb              0.0s
 => [lint-base 1/1] FROM docker.io/golangci/golangci-lint:v2.8.0-alpine@sha256:1194f3bfcbaeeb92d8d159fdfbe2a79d18ec0a222d9d984b1438906bca  0.0s
 => => resolve docker.io/golangci/golangci-lint:v2.8.0-alpine@sha256:1194f3bfcbaeeb92d8d159fdfbe2a79d18ec0a222d9d984b1438906bca416b51      0.0s
 => CACHED [base 2/3] RUN apk add --no-cache git rsync                                                                                     0.0s
 => CACHED [base 3/3] WORKDIR /app                                                                                                         0.0s
 => CACHED [lint 1/2] COPY --from=lint-base /usr/bin/golangci-lint /usr/bin/golangci-lint                                                  0.0s
 => [lint 2/2] RUN --mount=target=.     --mount=type=cache,target=/go/pkg/mod     --mount=type=cache,target=/root/.cache/go-build     --  85.8s
 => exporting to image                                                                                                                     3.8s
 => => exporting layers                                                                                                                    3.1s
 => => exporting manifest sha256:769fdb30ea8fb8fce8a868790e0651974fc7b28553ca0acf51e3c6c4beab7033                                          0.0s
 => => exporting config sha256:54d041ee39ac717803c398e8f70e29f54d2043c9ce8d5302fb7142a496383762                                            0.0s
 => => exporting attestation manifest sha256:e4104899832e892bf5cfbb27ccc3c1b4139dd3337df9203aacf2837f454318b0                              0.0s
 => => exporting manifest list sha256:514a27ad07a33e8ac19b579df7620bea4fd4dea0790c18a336fdb30f07f3f48e                                     0.0s
 => => naming to moby-dangling@sha256:514a27ad07a33e8ac19b579df7620bea4fd4dea0790c18a336fdb30f07f3f48e                                     0.0s
 => => unpacking to moby-dangling@sha256:514a27ad07a33e8ac19b579df7620bea4fd4dea0790c18a336fdb30f07f3f48e                                  0.6s
pnkcaht@pnkcaht:~/Documents/MCPgateway/mcp-gateway$ ```

[cutecatfann]

Thanks for the fixes! I retriggered