Docker Build and Deployment Guide (mcpo project)

Thanks to @BigUncle for the pull request

This guide systematically outlines the build, deployment, troubleshooting, and best practices for the mcpo project in Docker container environments, reflecting the project's current state.

I. Project Overview and Architecture

This project uses Docker and Docker Compose for containerized deployment of mcpo (Model Context Protocol OpenAPI Proxy). Core design principles include:

• Dynamic Dependency Installation: At container startup, the start.sh script reads config.json and dynamically installs required Python (uvx) and Node.js (npx) tools based on defined mcpServers.
• Non-Root User Execution: The container ultimately runs as non-root user appuser to enhance security.
• Dependency and Data Persistence: Through Docker Compose volume mounts, configuration, logs, data, and cache directories for uv and npm are persisted to the host machine.
• Flexible Source Configuration: Supports dynamic configuration of pip sources via build argument (PIP_SOURCE), and uses Aliyun mirror by default to accelerate apt.
• Environment Isolation: In start.sh, each MCP tool installation occurs in a sub-shell to avoid environment variable conflicts.

II. Build and Deployment Process

1. Environment Preparation

• Docker & Docker Compose: Docker 24+ and Docker Compose 2.x recommended.

• .env File: Create an .env file in the project root directory for sensitive information and configuration. Include MCPO_API_KEY. Refer to .env.example.

  # .env file example
  # pip source used during Docker build (optional, uses default source if empty)
  PIP_SOURCE=https://mirrors.aliyun.com/pypi/simple/
  
  # API Key required for mcpo runtime (required)
  MCPO_API_KEY=your_mcpo_api_key_here
  
  # Other API Keys that may be needed for mcp servers (according to config.json)
  # AMAP_MAPS_API_KEY=your_amap_key
  # ... other required environment variables
  

• config.json: Configure MCP servers to start. Refer to config.example.json.

• Network: Ensure access to Debian (Aliyun mirror), NodeSource, PyPI (or specified PIP_SOURCE).

2. Directory Structure and Key Files

• Dockerfile: Defines image build process.
  • Base image: python:3.13-slim
  • Installs: bash, curl, jq, nodejs (v22.x), git, uv (via pip)
  • User: Creates and runs as appuser.
  • Configuration: Supports PIP_SOURCE build argument.
• start.sh: Container entrypoint script.
  • Sets HOME, UV_CACHE_DIR, NPM_CONFIG_CACHE.
  • Creates persistence directories.
  • Reads config.json and dynamically installs MCP tools (using uvx or npx).
  • Starts mcpo main service.
• docker-compose.yml: Defines services, build parameters, volume mounts, environment variables.
  • Passes PIP_SOURCE to Dockerfile.
  • Mounts ./config.json, ./logs, ./data, ./node_modules, ./.npm, ./.uv_cache.
  • Loads .env as runtime environment variables via env_file.
• readme-docker.md: This document.
• test_mcp_tools.sh: Basic functionality test script.

3. Building the Image

# Pass PIP_SOURCE (compose will automatically read from .env if defined)
docker-compose build [--no-cache]

• --no-cache: Forces rebuild of all layers to ensure latest changes take effect.
• Build process uses PIP_SOURCE from .env file (if valid) to configure pip source.

4. Starting the Service

# Start service (run in background)
docker-compose up -d

• docker-compose.yml loads variables from .env as container runtime environment variables.
• start.sh executes, dynamically installing MCP tools defined in config.json.
• mcpo main service starts.

III. Common Issues and Solutions

1. npx: command not found / git: command not found

• Cause: npx (installed with nodejs) or git not installed or their paths not in appuser's PATH envi

... View full README on GitHub