mcp-dockhand: Instructions file for Claude Code

CLAUDE.md — MCP-Dockhand Server

Projektübersicht

MCP Server (Model Context Protocol) für Dockhand Docker Management. Wrapt die Dockhand REST API in 130+ MCP-Tools mit Streamable HTTP Transport.

Tech Stack

• Runtime: Node.js 22+
• Sprache: TypeScript (strict mode)
• MCP SDK: @modelcontextprotocol/sdk
• Validierung: Zod (aktuell v3, Migration auf v4 geplant)
• Build: npm run build (tsc)
• Typecheck: npm run typecheck
• Tests: Vitest (geplant — siehe Issue für Test-Suite)
• Docker: Multi-stage Build, non-root User, Healthcheck

Verzeichnisstruktur

src/
├── index.ts           # Entry Point, Express Server
├── server.ts          # MCP Server Factory (Multi-Session)
├── auth/              # Dockhand Session-Authentifizierung
├── client/            # HTTP Client mit Cookie-Management
├── tools/             # Tool-Definitionen (130+)
│   ├── containers.ts  # Container-Management (27 Tools)
│   ├── stacks.ts      # Stack-Management (21 Tools)
│   ├── images.ts      # Image-Management (9 Tools)
│   ├── networks.ts    # Netzwerk-Management (7 Tools)
│   ├── volumes.ts     # Volume-Management (9 Tools)
│   ├── git-stacks.ts  # Git-Stack-Management (15 Tools)
│   ├── environments.ts # Environment-Management (18 Tools)
│   ├── users.ts       # User/Rollen-Management (20 Tools)
│   ├── system.ts      # System/Health/Metrics (19 Tools)
│   └── ...            # Weitere Tool-Dateien
├── types/             # TypeScript-Typen
└── utils/             # Hilfsfunktionen

Konventionen

Code-Stil

• Alle Tool-Parameter mit Zod validieren
• encodeURIComponent() auf ALLEN Pfad-Parametern (Container-IDs, Stack-Namen etc.)
• Environment-ID als environmentId (number) — IMMER als Query-Parameter ?env=
• Session-basierte Auth — automatisches Re-Login bei 401
• SSE für Deploy-Operationen (postSSE Methode)

Tool-Definition Pattern

server.tool(
  'tool_name',
  'Beschreibung was das Tool tut',
  {
    environmentId: z.number().describe('Environment ID (required)'),
    name: z.string().describe('Resource name'),
    // Optionale Parameter:
    option: z.string().optional().describe('Optional parameter'),
  },
  async ({ environmentId, name, option }) => {
    const client = await getClient(session);
    const result = await client.get(`/api/endpoint/${encodeURIComponent(name)}`, { env: environmentId });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }
);