mcp-gateway CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is the Docker MCP Gateway - a CLI plugin that enables easy and secure running of Model Context Protocol (MCP) servers through Docker containers. The plugin acts as a gateway between AI clients and containerized MCP servers, providing isolation, security, and management capabilities.

Architecture

The codebase follows a gateway pattern where:

• AI Client connects to the MCP Gateway
• MCP Gateway (this CLI) manages multiple MCP Servers running in Docker containers

Key architectural components:

• Gateway: Core routing and protocol translation (cmd/docker-mcp/internal/gateway/)
• Client Management: Handles connections to AI clients (cmd/docker-mcp/client/)
• Server Management: Manages MCP server lifecycle (cmd/docker-mcp/server/)
• Catalog System: Manages available MCP servers (cmd/docker-mcp/catalog/)
• Security: Secrets management and OAuth flows (cmd/docker-mcp/secret-management/, cmd/docker-mcp/oauth/)

Development Commands

Building

# Build the CLI plugin locally
make docker-mcp

# Cross-compile for all platforms
make docker-mcp-cross

Testing

# Run all tests
make test

# Run integration tests specifically
make integration

# Run long-lived integration tests
go test -count=1 ./... -run 'TestLongLived'

# Run specific tests by pattern
go test -count=1 ./... -run 'TestIntegration'

# Run a single test file
go test ./cmd/docker-mcp/server/server_test.go

# Run tests with coverage
go test -cover ./...

Code Quality

# Format code
make format

# Run linter
make lint

# Run linter for specific platform
make lint-linux
make lint-darwin

# Run Go vet (static analysis)
go vet ./...

# Run Go mod tidy to clean dependencies
go mod tidy

Project Structure

• cmd/docker-mcp/ - Main CLI application entry point
• cmd/docker-mcp/internal/gateway/ - Core gateway implementation with client pooling, proxy management, and transport handling
• cmd/docker-mcp/internal/docker/ - Docker integration for container management
• cmd/docker-mcp/internal/mcp/ - MCP protocol implementations (stdio, SSE)
• cmd/docker-mcp/internal/desktop/ - Docker Desktop integration and authentication
• cmd/docker-mcp/catalog/ - Server catalog management commands
• cmd/docker-mcp/client/ - Client configuration and connection management
• cmd/docker-mcp/server/ - Server lifecycle management commands
• cmd/docker-mcp/tools/ - Tool execution and management
• examples/ - Usage examples and compose configurations
• docs/ - Technical documentation