Arcane-MCP-Server: Instructions file for Claude Code

Arcane MCP Server

MCP server for Docker management via the Arcane platform. 180 tools, 2 resources, 4 prompts, companion skill, Claude Code plugin.

Not affiliated with the Arcane project.

Build & Test

npm install
npm run build          # TypeScript → dist/
npm test               # vitest (50 tests)
npm run dev            # stdio mode
npm run dev:tcp        # HTTP mode
npm run update-api-spec  # Refresh OpenAPI spec from live instance

Architecture

• src/index.ts — stdio entry point (default)
• src/tcp-server.ts — HTTP/Streamable transport (--tcp flag)
• src/server.ts — McpServer factory, wires tools + resources + prompts
• src/client/arcane-client.ts — HTTP client with retry, SSL bypass, size limits
• src/auth/auth-manager.ts — JWT (auto-refresh) + API key auth
• src/config.ts — Config from env vars > config file > defaults
• src/constants.ts — All shared constants (timeouts, limits, versions)

Tools (180 across 25 modules in src/tools/)

All tools use server.registerTool() with:

• title — human-readable name
• description — what it does and returns
• annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• inputSchema — Zod schemas with .describe() on every param
• toolHandler() wrapper from src/utils/tool-helpers.ts — handles client init, error formatting, isError: true on failures

Adding a new tool

1. Find or create the tool module in src/tools/
2. Use server.registerTool() with the config object pattern (not deprecated server.tool())
3. Classify annotations: list/get = readOnly, delete/prune = destructive, external calls = openWorld
4. Use toolHandler() wrapper — return a plain string, it handles the MCP response envelope
5. Register in src/tools/index.ts
6. Verify: npm run build && grep -rc 'register("arcane_' dist/tools/*.js | awk -F: '{sum+=$2} END {print sum}' (expect 180)

Resources & Prompts

• src/resources/index.ts — 3 resources (arcane://environments, arcane://version, arcane://tools-config-notice)
• src/prompts/index.ts — 5 prompts (deploy-stack, troubleshoot-container, security-audit, cleanup-environment, arcane_configure_tools)
• Prompts reference real tool names — cross-check if adding/renaming tools