Docker Build and Deployment Guide (mcpo project)

Docker ビルドとデプロイガイド（mcpo プロジェクト）

プルリクエストをいただいた @BigUncle に感謝します。

このガイドでは、プロジェクトの現在の状態を踏まえ、Docker コンテナ環境における mcpo プロジェクトのビルド、デプロイ、トラブルシューティング、ベストプラクティスを体系的に説明します。

---

I. プロジェクトの概要とアーキテクチャ

このプロジェクトでは、mcpo（Model Context Protocol OpenAPI Proxy）のコンテナ化されたデプロイに Docker と Docker Compose を使用します。主な設計原則は次のとおりです。

• 動的な依存関係のインストール：コンテナの起動時に、start.sh スクリプトが config.json を読み込み、定義された mcpServers に基づいて必要な Python（uvx）および Node.js（npx）ツールを動的にインストールします。
• 非 root ユーザーでの実行：セキュリティを強化するため、最終的にコンテナは非 root ユーザー appuser として実行されます。
• 依存関係とデータの永続化：Docker Compose のボリュームマウントを通じて、設定、ログ、データ、uv と npm のキャッシュディレクトリをホストマシンに永続化します。
• 柔軟なソース設定：ビルド引数（PIP_SOURCE）による pip ソースの動的な設定をサポートし、apt の高速化のため、デフォルトで Aliyun ミラーを使用します。
• 環境の分離：start.sh では、環境変数の競合を避けるため、各 MCP ツールのインストールをサブシェル内で実行します。

---

II. ビルドとデプロイの手順

1. 環境の準備

• Docker と Docker Compose：Docker 24 以降と Docker Compose 2.x を推奨します。

• .env ファイル：機密情報と設定を保存するため、プロジェクトのルートディレクトリに .env ファイルを作成します。MCPO_API_KEY を含めてください。.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：起動する MCP サーバーを設定します。config.example.json を参照してください。

• ネットワーク：Debian（Aliyun ミラー）、NodeSource、PyPI（または指定した PIP_SOURCE）にアクセスできることを確認してください。

2. ディレクトリ構成と主要ファイル

• Dockerfile：イメージのビルド手順を定義します。
  • ベースイメージ：python:3.13-slim
  • インストールするもの：bash、curl、jq、nodejs（v22.x）、git、uv（pip 経由）
  • ユーザー：appuser を作成して実行します。
  • 設定：PIP_SOURCE ビルド引数をサポートします。
• start.sh：コンテナのエントリポイントスクリプトです。
  • HOME、UV_CACHE_DIR、NPM_CONFIG_CACHE を設定します。
  • 永続化用のディレクトリを作成します。
  • config.json を読み込み、MCP ツールを動的にインストールします（uvx または npx を使用）。
  • mcpo のメインサービスを起動します。
• docker-compose.yml：サービス、ビルドパラメーター、ボリュームマウント、環境変数を定義します。
  • PIP_SOURCE を Dockerfile に渡します。
  • ./config.json、./logs、./data、./node_modules、./.npm、./.uv_cache をマウントします。
  • env_file を通じて .env を実行時の環境変数として読み込みます。
• readme-docker.md：このドキュメントです。
• test_mcp_tools.sh：基本機能のテストスクリプトです。

3. イメージのビルド

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

• --no-cache：すべてのレイヤーを強制的に再ビルドし、最新の変更を確実に反映します。
• ビルドプロセスでは、.env ファイルの PIP_SOURCE（有効な場合）を使用して pip ソースを設定します。

4. サービスの起動

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

• docker-compose.yml は .env から変数を読み込み、コンテナの実行時環境変数として設定します。
• start.sh が実行され、config.json で定義された MCP ツールを動的にインストールします。
• mcpo のメインサービスが起動します。

---

III. よくある問題と解決策

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

• 原因：npx（nodejs とともにインストール）または git がインストールされていないか、そのパスが appuser の PATH 環境変数に含まれていません。
• 解決策：
  • Dockerfile の apt-get install に nodejs と git が含まれていることを確認してください。
  • ENV PATH ディレクティブに /usr/bin（apt でインストールされた nodejs と git が通常配置される場所）が含まれていることを確認してください。Dockerfile にはすでに /app/.local/bin:/usr/bin:/usr/local/bin:$PATH が含まれています。
  • docker-compose build --no-cache を使用して再ビルドしてください。

2. mkdir: cannot create directory '/root': Permission denied

• 原因：コンテナは root 以外のユーザー appuser として実行されますが、スクリプトや依存関係が /root ディレクトリ（デフォルトのキャッシュパスなど）への書き込みを試みます。
• 解決策：
  • ENV ディレクティブ（UV_CACHE_DIR、NPM_CONFIG_CACHE、HOME）を使用して、すべてのキャッシュディレクトリ（uv、npm）を /app にリダイレクトします。
  • start.sh の mkdir -p は、/app 配下のディレクトリのみを対象にします。
  • docker-compose.yml の対応するボリュームマウントパスを /app/... に更新します。

3. pip がカスタムソース（PIP_SOURCE）を使用しない

• 原因：ビルド時に PIP_SOURCE が Dockerfile に正しく渡されていません。
• 解決策：
  • .env ファイルに PIP_SOURCE=https://... が含まれていることを確認します。
  • docker-compose.yml の build.args セクションに - PIP_SOURCE=${PIP_SOURCE:-} が含まれていることを確認します。
  • Dockerfile で ARG PIP_SOURCE を受け取り、RUN レイヤー内で export PIP_INDEX_URL を使って設定します。

4. ネットワーク接続の低速化・失敗と依存関係のインストール

• 原因：ネットワーク接続の状態が悪く、公式ソースへのアクセスが遅い、またはタイムアウトしています。
• 解決策：
  • Dockerfile は、apt を高速化するために Aliyun ミラーを使用するよう設定されています。
  • .env の PIP_SOURCE を使って、pip に国内ミラーを設定できます。
  • Node.js（NodeSource）と uv（PyPI／ミラー）は引き続きネットワークに依存します。極端なケースでは、別の解決策を検討してください。

---

IV. 重要な注意事項とベストプラクティス

• root 以外のユーザー：コンテナは必ず appuser として実行してください。
• 永続化：状態と依存関係を保持するため、config.json、logs、data、node_modules、.npm、.uv_cache を明示的にマウントしてください。
• シークレット：API キーや機密情報は .env ファイルで管理し、env_file を通じて渡してください。.env をイメージに COPY したり、キーをハードコードしたりしないでください。.env ファイルは .gitignore に含めてください。
• 動的インストール：start.sh の動的インストール機能により柔軟性が高まりますが、初回起動時や config.json の変更後は起動時間が長くなります。
• バージョンの固定：再現性を高めるため、Dockerfile では uv のバージョン（pip install --user uv==X.Y.Z）を、config.json では npx パッケージのバージョン（@amap/[email protected]）を固定することをおすすめします。
• リソース制限：本番環境では、docker-compose.yml でサービスのメモリと CPU の上限を設定することを検討してください。
• ログ：ログはマウントされた ./logs ディレクトリに出力されるため、簡単に確認・管理できます。
• テスト：基本的な機能の確認には test_mcp_tools.sh スクリプトを使用してください。

---

V. コマンド早見表

• イメージをビルド：docker-compose build [--no-cache]
• サービスを起動（バックグラウンド）：docker-compose up -d