docker-mcp — summary for oracle review What Building a TypeS...

Prompt

docker-mcp — summary for oracle review What Building a TypeScript MCP server (@modelcontextprotocol/sdk, dockerode) that wraps the Docker Engine API as 27 MCP tools. Target: homelab Docker host at 192.168.1.111, developing on MacBook via DOCKER_HOST=tcp://.... Key decisions to scrutinize Decision Choice Why this matters Compose Shell out to docker compose CLI No dockerode compose support. Trade-off: feature parity but fragile parsing, no --format json on all subcommands. Transport stdio only (v1) Simple but no SSE fallback. Host spawns as subprocess. Config DOCKER_HOST env vars Zero-config for most users. dockerode reads Docker CLI env vars natively. Health check docker_ping tool (not resource) Tool because it's request-response. Returns connected, dockerVersion, apiVersion, os, arch, kernelVersion. Graceful startup Log warning, don't crash if Docker unavailable Server starts even without daemon; tools return descriptive errors. Module structure src/tools/*.ts per capability containers.ts, images.ts, volumes.ts, compose.ts, health.ts Architecture src/index.ts → MCP server setup, tool registration, stdio transport src/config.ts → Reads env vars, creates dockerode client src/tools/ → One file per capability, one function per tool Data flow: stdio JSON-RPC → handler → dockerode API (or exec compose) → JSON response. Scope boundaries - In: containers, images, volumes, compose operations - Out (v1): Swarm, secrets/configs, HTTP/SSE transport, multi-host, per-tool auth Things I want oracle's opinion on 1. Compose shell-out approach: Is this the right call, or should we parse compose YAML in-process and use Engine API directly? Shell-out is simpler but brittle — errors are text-only, no structured output for up/down/pull. The alternative is full compose YAML parsing + individual API calls (complex, but typed). 2. Docker host connection strategy: dockerode reads DOCKER_HOST env var automatically. For the homelab use case (192.168.1.111), should we also support SSH tunneling or docker context? Or is plain TCP + TLS sufficient? 3. Error handling pattern: For dockerode calls, should each tool handler wrap errors individually (granular messages) or is a centralized error boundary sufficient? The token-reduction goal means error responses should be compact but actionable. 4. Testing strategy: 22 dockerode-based tools + 5 compose shell-out tools. Unit tests with mocked dockerode for the first, but compose tests require actual docker compose. Any patterns to avoid brittle compose tests? 5. Any gap in the 27-tool inventory — missing something obvious for homelab Docker management? Files for context - openspec/changes/docker-engine-mcp/proposal.md — why and what - openspec/changes/docker-engine-mcp/design.md — architecture and decisions - openspec/changes/docker-engine-mcp/specs/*/spec.md — per-capability requirements - openspec/changes/docker-engine-mcp/tasks.md — 37 implementation tasks think of other things I might wish to consider for token optimisation.