Add Compose Validate tool and auto-track future MISSING_TOOL API coverage gaps

[Seger85]

Context

Dockhand v1.0.43 added a useful Compose preflight endpoint:

POST /api/stacks/{name}/validate

The current mcp-dockhand API schema/coverage machinery already sees this endpoint, but there is no corresponding MCP tool yet.

This also exposed a small automation gap: .github/workflows/api-schema-sync.yml only creates/updates an issue when validate-mcp-tools.mjs fails. A newly detected MISSING_TOOL is intentionally a coverage finding rather than a hard validation failure, so a new Dockhand endpoint can appear in docs/coverage.md without creating an actionable tracking issue. The previous coverage tracker #60 was closed once coverage reached zero.

Rather than opening a new manual issue for every Dockhand release, it would be nice to make endpoint coverage self-tracking.

1. Add MCP coverage for Compose Validate

Please expose Dockhand's POST /api/stacks/{name}/validate through an MCP tool (name at maintainer discretion, e.g. validate_stack_compose).

The Dockhand v1.0.43 contract accepts the stack name plus environment context and Compose validation input, and returns structured findings/counts. Relevant fields include:

• environment id / env
• compose content
• optional validation config (disabled rules / severity overrides)
• optional env vars
• existing-stack context where supported
• response findings with ruleId, severity, message, optional hint/service/line/fix metadata
• response counts for error/warn/info

This would make Dockhand's native preflight linter available to agents before controlled stack creation/deploy workflows, without duplicating that logic in downstream guards.

Acceptance

• MCP tool calls the v1.0.43 Compose Validate endpoint with the selected environment preserved.
• Request/response schema is represented accurately.
• Findings and counts are returned without unnecessary transformation.
• No secret/env values are logged or exposed beyond what the caller explicitly supplies/receives.
• Tests cover environment routing and representative error/warn/info findings.

2. Make future MISSING_TOOL coverage gaps self-tracking

Extend the existing api-schema-sync/coverage workflow so newly discovered Dockhand endpoints do not require a manual issue each time.

Suggested behavior:

1. Run the existing schema extraction + coverage validation as today.
2. If MISSING_TOOL > 0, create or update one dedicated coverage-tracker issue.
3. Keep that same issue current as endpoints are added/removed instead of opening one issue per endpoint/release.
4. When MISSING_TOOL == 0, automatically close/resolve the tracker (or mark it clean).
5. If new gaps appear later, reopen/update the tracker or create a replacement only if reopening is not practical.
6. Keep hard schema/contract validation failures separate from ordinary missing-tool coverage findings, so a harmless new Dockhand endpoint does not falsely make CI red.

This could reuse the existing coverage-tracker concept from #60 and docs/coverage.md; the important part is that coverage drift becomes actionable automatically without issue spam.

Automation acceptance

• Adding a synthetic/new Dockhand endpoint with no MCP mapping results in exactly one actionable coverage tracker.
• Repeated daily runs update the same tracker and do not create duplicates.
• Implementing the missing MCP tool removes the finding and automatically resolves the tracker when coverage returns to zero.
• Existing hard validation-failure issue behavior remains unchanged.

References

• Track upstream Dockhand PR #1341 (OpenAPI) for Level-2 codegen upgrade #57 — OpenAPI / schema-level validation direction
• MCP API Coverage tracking: 44 endpoints without MCP tool #60 — previous API coverage tracker
• Dockhand v1.0.43 — introduced Compose Validate

Thanks for continuing to make the API coverage tooling increasingly self-maintaining — it is already doing most of the hard work here.

Greetings from Gerry — Bremen isn't far from Hamburg 🙂