Track upstream Dockhand PR #816 (OpenAPI) for Level-2 codegen upgrade

[strausmann]

Context

The validator (`scripts/validate-mcp-tools.mjs`) currently does Endpoint-Coverage-Checks but cannot do schema-level validation of MCP tool params vs Dockhand API body shapes. This let bugs like the bogus `rawContent` parameter on `update_stack_env` (issue #56) slip through unnoticed for months — the param was in the tool schema but the route ignored it.

A proper schema-driven approach needs an upstream OpenAPI specification from Dockhand. That is exactly the goal of upstream PR Finsys/dockhand#816 ("Add OpenAPI/Swagger documentation for REST API").

Why this matters for mcp-dockhand

Three coverage levels possible:

• Level 0 (today): Endpoint-only extraction via `scripts/extract-dockhand-api.mjs` — walks `+server.ts` files, lists routes + HTTP methods. Catches missing/orphaned tools but not param-level drift.
• Level 1: Validator extended with manual body-shape annotations per route. Brittle, high maintenance.
• Level 2: Dockhand publishes OpenAPI → mcp-dockhand fetches the spec, validates tool schemas against it automatically. Catches `rawContent`-class bugs at PR time.
• Level 3: OpenAPI-driven codegen — mcp-dockhand tool stubs generated from OpenAPI, manual descriptions overlaid. Drift impossible.

We are at Level 0 today. PR #816 is the precondition for Level 2+.

Action items

• Monitor feat: Add OpenAPI/Swagger documentation for REST API Finsys/dockhand#816 for merge status
• When merged: read the OpenAPI artefact format (path, generation step in Dockhand build)
• Plan Level-2 implementation: fetch/cache OpenAPI in `scripts/extract-dockhand-api.mjs`, extend `validate-mcp-tools.mjs` to read request/response schemas
• Optional Level-3 evaluation: openapi-typescript or similar codegen for tool stubs

Status of PR #816 (as of 2026-05-15)

• OPEN, conflicting state (146 commits behind upstream main)
• 5 OpenAPI-specific commits on the branch + 2 prior "merge upstream" commits that are now stale
• Cleanup option: cherry-pick the 5 real commits onto fresh upstream/main, force-push to fork

References

• Upstream PR: feat: Add OpenAPI/Swagger documentation for REST API Finsys/dockhand#816
• Related fix issue: Fix: update_stack_env rawContent param is non-functional + missing update_stack_env_raw tool #56
• Existing validator: `scripts/validate-mcp-tools.mjs`
• Schema baseline: `docs/dockhand-api-baseline.json`