mcp-optimizer

MCP Optimizer

🚀 PuLP と OR-Tools に対応した数理最適化 MCP サーバー

📖 クイックリンク： 🚀 クイックスタート | 🔧 macOS のトラブルシューティング | 📊 使用例 | 🎯 機能

🚀 クイックスタート

推奨インストール方法（優先順位順）

1. 🐳 Docker（推奨）- クロスプラットフォーム

すべての機能を利用できる、最も安定した方法です

# Run with STDIO transport (for MCP clients)
docker run --rm -i ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Run with SSE transport (for remote clients)
docker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \
  ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Check SSE endpoint
curl -i http://localhost:8000/sse

2. 📦 pip + venv - クロスプラットフォーム

標準的な方法です

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate  # Windows

# Install mcp-optimizer
pip install mcp-optimizer

# For SSE issues, use stable dependency versions:
# pip install "mcp-optimizer[stable]"

# Run (STDIO mode recommended)
mcp-optimizer --transport stdio

3. 🚀 uvx - Linux/Windows（完全対応）、macOS（一部対応）

# Linux/Windows - works out of the box
uvx mcp-optimizer

# macOS - requires Python 3.12
uvx --python python3.12 mcp-optimizer

# STDIO mode recommended
uvx mcp-optimizer --transport stdio

macOS ユーザーの方へ： OR-Tools 関連のエラーが発生した場合は、自動修正スクリプトについて 🔧 macOS uvx のトラブルシューティング セクションをご覧ください。

🍎 macOS 固有の注意点

OR-Tools のサポート：

• uvx：PuLP のみ（機能制限あり）
• pip：OR-Tools を完全サポート
• Docker：OR-Tools を完全サポート

pip で OR-Tools を完全に利用するには：

# Install OR-Tools via Homebrew
brew install or-tools

# Then install mcp-optimizer
pip install "mcp-optimizer[stable]"

トランスポートモードの推奨事項

インストール方法	推奨トランスポート	理由
Docker	SSE	高い安定性
pip + venv	STDIO	新しいバージョンでの依存関係の問題を回避
uvx	STDIO	最大限の互換性

LLM クライアントとの連携

Claude Desktop との連携

オプション 1：Docker を使用（推奨）

1. claude.ai から Claude Desktop をインストールします
2. Docker イメージを取得します：

docker pull ghcr.io/dmitryanchikov/mcp-optimizer:latest

3. claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/dmitryanchikov/mcp-optimizer:latest",
        "python", "main.py"
      ]
    }
  }
}

4. Claude Desktop を再起動し、🔨 ツールアイコンを確認します

オプション 2：pip + venv を使用

# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install mcp-optimizer

次に、Claude Desktop の設定に追加します：

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "mcp-optimizer"
    }
  }
}

オプション 3：uvx を使用 claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "uvx",
      "args": ["mcp-optimizer"]
    }
  }
}

注：macOS では uvx の機能は制限されます（PuLP ソルバーのみ）。または 🔧 macOS uvx のトラブルシューティング をご覧ください

Docker の詳細設定（リモート MCP クライアント向け）

# Run SSE server on port 8000 (uses environment variable)
docker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \
  ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Or with CLI argument and custom port
docker run -d -p 9000:9000 ghcr.io/dmitryanchikov/mcp-optimizer:latest \
  python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000

# Check server status
docker logs <container-name>

# Verify SSE endpoint (should show event stream)
curl -i http://localhost:8000/sse

SSE エンドポイント：http://localhost:8000/sse（MCP 通信用の Server-Sent Events）

Cursor との連携

1. Cursor に MCP 拡張機能をインストールします
2. ワークスペースの設定に mcp-optimizer を追加します（Docker を推奨）：

{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/dmitryanchikov/mcp-optimizer:latest",
        "python", "main.py"
      ]
    }
  }
}

その他の設定：

// Using pip installation
{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "mcp-optimizer"
    }
  }
}

// Using uvx (limited functionality on macOS)
{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "uvx",
      "args": ["mcp-optimizer"]
    }
  }
}

その他の LLM クライアント

その他の MCP 対応クライアント（Continue、Cody など）では、同様の設定方法を使用します。推奨順位：

1. Docker（プラットフォームを問わず高い安定性）
2. pip + venv（標準的な Python の方法）
3. uvx（手軽にテストできますが、macOS では機能制限あり）

高度なインストールオプション

ローカル開発

# Clone the repository
git clone https://github.com/dmitryanchikov/mcp-optimizer.git
cd mcp-optimizer

# Install dependencies with uv
uv sync --extra dev

# Run the server
uv run python main.py

ローカルでのパッケージのビルドと実行

テストや開発では、パッケージをローカルでビルドし、uvx で実行できます：

# Build the package locally
uv build

# Run with uvx from local wheel file
uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer

# Or run with help to see available options
uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer --help

# Test the local package with a simple MCP message
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer

注：ローカルビルドでは、dist/ ディレクトリに wheel（.whl）ファイルとソース配布物（.tar.gz）ファイルの両方が作成されます。uvx でのインストールには、処理が速くコンパイルも不要な wheel ファイルを推奨します。

カスタム設定での Docker

# Build locally with optimization
git clone https://github.com/dmitryanchikov/mcp-optimizer.git
cd mcp-optimizer
docker build -t mcp-optimizer:optimized .
docker run -p 8000:8000 mcp-optimizer:optimized

# Check optimized image size (398MB vs 1.03GB original - 61% reduction!)
docker images mcp-optimizer:optimized

# Test the optimized image
./scripts/test_docker_optimization.sh

スタンドアロンサーバーのコマンド

# Run directly with uvx (no installation needed)
uvx mcp-optimizer

# Or run specific commands
uvx mcp-optimizer --help

# With pip installation
mcp-optimizer

# Or run with Python module (use main.py for stdio mode)
python main.py

トランスポートモード

MCP Optimizer は、次の 2 つの MCP トランスポートプロトコルをサポートしています：

• STDIO：MCP クライアント（Claude Desktop、Cursor など）と直接連携するための標準入出力
• SSE：Web ベースの MCP クライアントやリモート連携向けの HTTP 経由の Server-Sent Events

STDIO トランスポート（デフォルト - Claude Desktop などの MCP クライアント向け）

# Default STDIO mode for MCP protocol
uvx mcp-optimizer
# or
uvx mcp-optimizer --transport stdio
# or
uv run python -m mcp_optimizer.main --transport stdio
# or
python main.py

SSE トランスポート（リモート MCP クライアント向け）

# SSE mode for remote MCP clients (default port 8000)
uvx mcp-optimizer --transport sse
# or
uv run python -m mcp_optimizer.main --transport sse

# Custom host and port
uvx mcp-optimizer --transport sse --host 0.0.0.0 --port 9000
# or
uv run python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000

# With debug mode
uvx mcp-optimizer --transport sse --debug --log-level DEBUG

使用可能な CLI オプション

# Show all available options
uvx mcp-optimizer --help

# Options:
#   --transport {stdio,sse}    MCP transport protocol (default: stdio)
#   --port PORT               Port for SSE transport (default: 8000)
#   --host HOST               Host for SSE transport (default: 127.0.0.1)
#   --debug                   Enable debug mode
#   --reload                  Enable auto-reload for development
#   --log-level {DEBUG,INFO,WARNING,ERROR}  Logging level (default: INFO)
#
# Environment Variables:
#   TRANSPORT_MODE={stdio,sse}  Override transport mode
#   SERVER_HOST=0.0.0.0        Override server host
#   SERVER_PORT=8000           Override server port

🔧 プラットフォーム互換性とトラブルシューティング

macOS 互換性

✅ すべての機能を利用可能：

• Homebrew + pip：brew install or-tools && pip install mcp-optimizer
• 仮想環境：python -m venv venv && source venv/bin/activate && pip install ortools mcp-optimizer
• Docker：コンテナー内で OR-Tools の全機能を利用可能

⚠️ 機能に制限があります：

• uvx（隔離環境）：OR-Tools のネイティブライブラリパスのため、PuLP ソルバーのみ利用可能です
• フォールバック動作：OR-Tools が利用できない場合、自動的に PuLP に切り替わります

よくある問題と解決策：

1. OR-Tools の「Library not loaded」エラー：

   # Solution: Install via Homebrew
   brew install or-tools
   # Then use regular pip/venv instead of uvx
   

2. uvx に OR-Tools の警告が表示される：

   WARNING: OR-Tools not available: No module named 'ortools'
   

   これは想定される動作です。uvx では PuLP ソルバーを使用したフォールバック機能が提供されます。

3. macOS でのベストプラクティス：

   • 本番環境へのデプロイには Docker を使用します
   • 開発には Homebrew + pip を使用します
   • 簡単なテストには uvx を使用します（機能に制限があります）

Linux／Windows 互換性

✅ すべての機能を利用可能：

• uvx：OR-Tools をそのまま利用できます
• pip：標準的なインストール方法です
• Docker：本番環境での使用を推奨します

プラットフォーム別のソルバー利用可否

プラットフォーム	uvx	pip	Docker
macOS	PuLP のみ	✅ 全機能	✅ 全機能
Linux	✅ 全機能	✅ 全機能	✅ 全機能
Windows	✅ 全機能	✅ 全機能	✅ 全機能

ソルバーの機能：

• OR-Tools：高度なアルゴリズム（CP-SAT、ルーティング、スケジューリング）
• PuLP：基本的な線形計画法と信頼性の高いフォールバック

🔧 macOS の uvx に関するトラブルシューティング

問題：uvx で OR-Tools ライブラリに関する問題が発生する

よくあるエラーメッセージ：

Library not loaded: /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib
ImportError: No module named 'ortools'
WARNING: OR-Tools not available

根本原因：OR-Tools のバイナリホイールにはハードコードされたライブラリパスが含まれており、uvx の隔離環境では正しく動作しません。これは、uvx による依存関係の隔離方法に起因する macOS 固有の問題です。

📊 インストール方法別の機能への影響

✅ uvx とフォールバック（PuLP ソルバーのみ）で利用可能：

• 線形計画法 - 基本的な最適化、シンプレックス法
• 金融最適化 - ポートフォリオ最適化、リスク管理
• 生産計画 - リソース配分、在庫管理

❌ uvx では利用できません（OR-Tools が必要）：

• 割り当て問題 - ハンガリアン法、輸送問題
• 整数計画法 - 混合整数計画法、二値計画法（SCIP/CBC）
• ナップサック問題 - 離散最適化、複数のバリエーション
• 車両ルーティング - TSP、CVRP、時間枠（制約プログラミング）
• ジョブスケジューリング - CP-SAT ソルバー、リソース計画

🛠️ 解決策（推奨順）

1. 自動修正スクリプト（推奨）

# Smart adaptive script - no hardcoded versions!
# Automatically detects your system libraries and Python versions
./scripts/fix_macos_uvx.sh

# Then uvx works with full functionality
uvx mcp-optimizer --transport stdio

2. 手動で修正する

# Install system dependencies
brew install or-tools scip

# Create symlink for hardcoded path
sudo mkdir -p /Users/corentinl/work/stable/temp_python3.13/lib/
sudo ln -sf /opt/homebrew/lib/libscip.9.2.dylib /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib

# Test fix
uvx mcp-optimizer --help

3. pip を使用する（常に動作します）

# Install dependencies first
brew install or-tools

# Install package
pip install mcp-optimizer
mcp-optimizer

4. Docker を使用する（本番環境に対応）

docker run -p 8000:8000 mcp-optimizer

🎯 機能

サポートされている最適化問題の種類：

• 線形計画法 - 線形目的関数の最大化／最小化
• 割り当て問題 - ハンガリアン法を使用した最適なリソース配分
• 輸送問題 - 物流とサプライチェーンの最適化
• ナップサック問題 - 最適なアイテム選択（0-1、有界、非有界）
• ルーティング問題 - 時間枠を含む TSP と VRP
• スケジューリング問題 - ジョブとシフトのスケジューリング
• 整数計画法 - 離散最適化問題
• 金融最適化 - ポートフォリオ最適化とリスク管理
• 生産計画 - 複数期間にわたる生産計画

テスト

自動テストスクリプト

簡易テスト：

# Test local package build and functionality
./scripts/test_local_package.sh

# Test Docker container build and functionality  
./scripts/test_docker_container.sh

# Run comprehensive test suite (both package and Docker)
./scripts/test_all.sh

# Run only specific tests
./scripts/test_all.sh --skip-docker    # Skip Docker tests
./scripts/test_all.sh --skip-package   # Skip package tests

手動テスト：

# Run simple functionality tests
uv run python tests/test_integration/comprehensive_test.py

# Run comprehensive integration tests
uv run python tests/test_integration/comprehensive_test.py

# Run all unit tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src/mcp_optimizer --cov-report=html

テストスクリプトの機能：

• ✅ ローカルパッケージのテスト：ビルド、STDIO／SSE モード、CLI 機能
• ✅ Docker コンテナのテスト：イメージのビルド、環境変数、ヘルスチェック
• ✅ 包括的なテストスイート：詳細なレポートを伴う並列実行
• ✅ 自動クリーンアップ：テスト後にプロセスとコンテナをクリーンアップ
• ✅ クロスプラットフォーム：macOS、Linux で動作します（コンテナのテストには Docker が必要です）

要件：

• ローカルテストの場合：uv、curl、lsof、gtimeout／timeout
• Docker テストの場合：docker とローカルテストの要件
• macOS：brew install coreutils（gtimeout 用）

CI/CD との統合：

# GitHub Actions example
- name: Test Package
  run: ./scripts/test_local_package.sh
- name: Test Docker
  run: ./scripts/test_docker_container.sh

📊 使用例

線形計画法

from mcp_optimizer.tools.linear_programming import solve_linear_program

# Maximize 3x + 2y subject to:
# x + y <= 4
# 2x + y <= 6
# x, y >= 0

objective = {"sense": "maximize", "coefficients": {"x": 3, "y": 2}}
variables = {
    "x": {"type": "continuous", "lower": 0},
    "y": {"type": "continuous", "lower": 0}
}
constraints = [
    {"expression": {"x": 1, "y": 1}, "operator": "<=", "rhs": 4},
    {"expression": {"x": 2, "y": 1}, "operator": "<=", "rhs": 6}
]

result = solve_linear_program(objective, variables, constraints)
# Result: x=2.0, y=2.0, objective=10.0

割り当て問題

from mcp_optimizer.tools.assignment import solve_assignment_problem

workers = ["Alice", "Bob", "Charlie"]
tasks = ["Task1", "Task2", "Task3"]
costs = [
    [4, 1, 3],  # Alice's costs for each task
    [2, 0, 5],  # Bob's costs for each task
    [3, 2, 2]   # Charlie's costs for each task
]

result = solve_assignment_problem(workers, tasks, costs)
# Result: Total cost = 5.0 with optimal assignments

ナップサック問題

from mcp_optimizer.tools.knapsack import solve_knapsack_problem

items = [
    {"name": "Item1", "weight": 10, "value": 60},
    {"name": "Item2", "weight": 20, "value": 100},
    {"name": "Item3", "weight": 30, "value": 120}
]

result = solve_knapsack_problem(items, capacity=50)
# Result: Total value = 220.0 with optimal item selection

ポートフォリオ最適化

from mcp_optimizer.tools.financial import optimize_portfolio

assets = [
    {"name": "Stock A", "expected_return": 0.12, "risk": 0.18},
    {"name": "Stock B", "expected_return": 0.10, "risk": 0.15},
    {"name": "Bond C", "expected_return": 0.06, "risk": 0.08}
]

result = optimize_portfolio(
    assets=assets,
    objective="minimize_risk",
    budget=10000,
    risk_tolerance=0.15
)
# Result: Optimal portfolio allocation with minimized risk

🏗️ アーキテクチャ

mcp-optimizer/
├── LICENSE                     # MIT License
├── README.md                   # Project documentation
├── CHANGELOG.md               # Release notes
├── CONTRIBUTING.md            # Contribution guidelines
├── pyproject.toml             # Python project configuration
├── uv.lock                    # Dependency lock file
├── main.py                    # Entry point
├── Dockerfile                 # Main Docker configuration
├── docker-compose.yml         # Multi-service setup
├── .dockerignore             # Docker ignore rules
├── .gitignore                # Git ignore rules
├── .python-version           # Python version specification
├── src/mcp_optimizer/        # Main source code
│   ├── __init__.py
│   ├── __main__.py           # Module entry point
│   ├── main.py               # Application entry point
│   ├── mcp_server.py         # MCP server implementation
│   ├── config.py             # Configuration management
│   ├── tools/                # 9 categories of optimization tools
│   │   ├── linear_programming.py
│   │   ├── assignment.py
│   │   ├── knapsack.py
│   │   ├── routing.py
│   │   ├── scheduling.py
│   │   ├── financial.py
│   │   └── production.py
│   ├── solvers/              # PuLP and OR-Tools integration
│   │   ├── pulp_solver.py
│   │   └── ortools_solver.py
│   ├── schemas/              # Pydantic validation schemas
│   └── utils/                # Utility functions
├── tests/                    # Comprehensive test suite
│   ├── test_tools/           # Tool-specific tests
│   ├── test_solvers/         # Solver tests
│   └── test_integration/     # Integration tests
├── scripts/                  # Automation scripts
├── examples/                 # Usage examples and prompts
│   ├── en/                   # English examples
│   └── ru/                   # Russian examples
├── k8s/                      # Kubernetes deployment manifests
└── monitoring/               # Grafana/Prometheus setup
    └── grafana/
        └── datasources/

🧪 テスト結果

✅ 包括的なテストスイート

🧪 Starting Comprehensive MCP Optimizer Tests
==================================================
✅ Server Health PASSED
✅ Linear Programming PASSED
✅ Assignment Problems PASSED  
✅ Knapsack Problems PASSED
✅ Routing Problems PASSED
✅ Scheduling Problems PASSED
✅ Financial Optimization PASSED
✅ Production Planning PASSED
✅ Performance Test PASSED

📊 Test Results: 9 passed, 0 failed
🎉 All tests passed! MCP Optimizer is ready for production!

✅ 単体テスト

• 66 件のテストが成功、9 件をスキップ
• 実行時間：0.45 秒
• すべてのコアコンポーネントが機能

📈 パフォーマンス指標

• 線形計画法：約 0.01 秒
• 割り当て問題：約 0.01 秒
• ナップサック問題：約 0.01 秒
• 複雑なテストスイート：3 件の最適化問題で 0.02 秒
• 全体的なパフォーマンス：🚀 優秀です！

🔧 技術的な詳細

コアソルバー

• OR-Tools：割り当て、輸送、ナップサック問題向け
• PuLP：線形／整数計画法向け
• FastMCP：MCP サーバーとの統合向け

サポートされているソルバー

• CBC、GLPK、GUROBI、CPLEX（PuLP 経由）
• SCIP、CP-SAT（OR-Tools 経由）

主な機能

• ✅ MCP プロトコルとの完全な統合
• ✅ 包括的な入力検証
• ✅ 堅牢なエラー処理
• ✅ 高性能な最適化
• ✅ 本番環境に対応したアーキテクチャ
• ✅ 広範なテストカバレッジ
• ✅ Docker と Kubernetes のサポート

📋 要件

• Python 3.11 以降
• uv（依存関係の管理用）
• OR-Tools（自動的にインストールされます）
• PuLP（自動的にインストールされます）

🚀 本番環境へのデプロイ

Docker

# Build image
docker build -t mcp-optimizer .

# Run container
docker run -p 8000:8000 mcp-optimizer

Kubernetes

# Deploy to Kubernetes
kubectl apply -f k8s/

モニタリング

# Start monitoring stack
docker-compose up -d

🎯 プロジェクトのステータス

✅ 本番環境対応済み 🚀

• すべてのコア最適化ツールを実装し、テスト済み
• MCP サーバーが完全に機能
• 包括的なテストカバレッジ（単体テスト 66 件＋統合テスト 9 件）
• OR-Tools との統合が正常に動作することを確認済み
• パフォーマンスを最適化済み（複雑なテストスイートを 30 秒未満で実行）
• 本番環境へのデプロイ準備完了

📖 使用例

examples/ ディレクトリには、LLM（大規模言語モデル）で MCP Optimizer を使用するための実用的な例とプロンプトが含まれています。

利用可能な例

• 📊 線形計画法（RU | EN）
  • 生産の最適化、食事計画、輸送、配合の問題
• 👥 割り当て問題（RU | EN）
  • 従業員とプロジェクトの割り当て、機械と注文の割り当て、タスクの配分
• 💰 ポートフォリオ最適化（RU | EN）
  • 投資ポートフォリオ、退職後の資金計画、リスク管理

例の使用方法

1. LLM との統合：プロンプトのテキストをコピーし、MCP Optimizer にアクセスできる LLM に渡します
2. API の直接利用：提供されている API 構造を MCP Optimizer の関数で直接使用します
3. 学習：さまざまな最適化問題の種類と定式化について理解します

各例には次の内容が含まれています。

• 問題の説明と現実世界のシナリオ
• LLM 向けのすぐに使えるプロンプト
• 技術的な API 構造
• よく使われる起動フレーズ
• 実用的な用途

🔄 最近の更新

最新リリースの機能：

1. 関数のエクスポート - すべてのツールモジュールにエクスポート可能な関数を追加しました：

   • linear_programming.py の solve_linear_program()
   • assignment.py の solve_assignment_problem()
   • knapsack.py の solve_knapsack_problem()
   • financial.py の optimize_portfolio()
   • production.py の optimize_production()

2. テストの強化 - 正しい関数シグネチャを使用するよう、包括的なテストスイートを更新しました

3. OR-Tools との統合 - すべての OR-Tools コンポーネントが完全に機能することを確認しました

🚀 リリースプロセスの完全自動化

新しい簡略化された Git フロー（3 ステップ！）

このプロジェクトでは、リリースプロセスが完全に自動化されています。

1. リリースブランチを作成

# For minor release (auto-increment)
uv run python scripts/release.py --type minor

# For specific version
uv run python scripts/release.py 0.2.0

# For hotfix
uv run python scripts/release.py --hotfix --type patch

# Preview changes
uv run python scripts/release.py --type minor --dry-run

2. main に PR を作成

# Create PR: release/v0.3.0 → main
gh pr create --base main --head release/v0.3.0 --title "Release v0.3.0"

3. PR をマージ - 完了！🎉

PR のマージ後、以下が自動的に実行されます：

• ✅ タグ v0.3.0 を作成
• ✅ PyPI に公開
• ✅ Docker イメージを公開
• ✅ GitHub Release を作成
• ✅ main を develop にマージ
• ✅ リリースブランチをクリーンアップ

manual_finalize_release.py を手動で実行する必要はもうありません！

🔒 安全な検出：GitHub のブランチ保護と自動リリース検出を組み合わせたハイブリッド方式を使用しています。詳しくはリリースプロセスをご覧ください。

自動リリースパイプライン

CI/CD パイプラインでは、以下が自動的に処理されます：

• ✅ リリース候補：release/* ブランチからビルド
• ✅ 本番リリース：main のバージョンタグによって開始
• ✅ PyPI への公開：タグ作成時に自動実行
• ✅ Docker イメージ：マルチアーキテクチャビルド
• ✅ GitHub Releases：アーティファクトとリリースノートを含む

CI/CD パイプライン

GitHub Actions ワークフローでは、以下が自動的に実行されます：

• ✅ Python 3.11 と 3.12 でテストを実行
• ✅ セキュリティスキャンを実施
• ✅ Docker イメージをビルドしてプッシュ
• ✅ タグ作成時に PyPI へ公開
• ✅ GitHub リリースを作成

PyPI への公開要件

• GitHub リポジトリに PYPI_API_TOKEN シークレットを設定する
• すべてのテストに合格していることを確認する
• セマンティックバージョニングに従う

🛠️ 開発ツール

デバッグツール

デバッグスクリプトを使って MCP サーバーの構造を調査できます：

# Run debug tools to check server structure
uv run python scripts/debug_tools.py

# This will show:
# - Available MCP tools
# - Tool types and attributes
# - Server configuration

包括的なテスト

統合テストスイート全体を実行します：

# Run comprehensive tests
uv run python tests/test_integration/comprehensive_test.py

# This tests:
# - All optimization tools (9 categories)
# - Server health and functionality
# - Performance benchmarks
# - End-to-end workflows

Docker のビルド手順

イメージの詳細

• ベース：Python 3.12 Slim（Debian ベース）
• サイズ：約 649MB（マルチステージビルドで最適化）
• アーキテクチャ：マルチプラットフォーム対応（x86_64、ARM64）
• セキュリティ：非 root ユーザー、最小限の依存関係
• パフォーマンス：Python バイトコードを最適化し、ビルド生成物をクリーンアップ

ローカルビルドコマンド

# Standard build
docker build -t mcp-optimizer:latest .

# Build with development dependencies
docker build --build-arg ENV=development -t mcp-optimizer:dev .

# Build with cache mount for faster rebuilds
docker build --mount=type=cache,target=/build/.uv -t mcp-optimizer .

# Check image size
docker images mcp-optimizer

# Run container
docker run -p 8000:8000 mcp-optimizer:latest

# For development with volume mounting
docker run -p 8000:8000 -v $(pwd):/app mcp-optimizer:latest

# Test container functionality
docker run --rm mcp-optimizer:latest python -c "from mcp_optimizer.mcp_server import create_mcp_server; print('✅ MCP Optimizer works!')"

🤝 コントリビューション

コントリビューションを歓迎します！ガイドラインについてはCONTRIBUTING.mdをご覧ください。

Git フローポリシー

このプロジェクトでは、標準的な Git Flow ワークフローを採用しています：

• 機能ブランチ → develop ブランチ
• リリースブランチ → main ブランチ
• ホットフィックスブランチ → main ブランチと develop ブランチ

📚 ドキュメント：

• コントリビューションガイド - 開発ワークフローと Git Flow ポリシーの全容
• リリースプロセス - リリースの作成方法と自動化について
• リポジトリのセットアップ - ブランチ保護とセキュリティ設定を含むセットアップガイドの全容

開発環境のセットアップ

# Clone and setup
git clone https://github.com/dmitryanchikov/mcp-optimizer.git
cd mcp-optimizer

# Create feature branch from develop
git checkout develop
git checkout -b feature/your-feature-name

# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run linting
uv run ruff check src/
uv run mypy src/

# Create PR to develop branch (not main!)

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳しくは LICENSE ファイルをご覧ください。

🙏 謝辞

• OR-Tools - Google の最適化ツール
• PuLP - Python での線形計画法
• FastMCP - 高速な MCP サーバー実装

📞 サポート

• 📧 メール：[email protected]
• 🐛 問題：GitHub Issues
• 📖 ドキュメント：docs/

---

最適化コミュニティのために ❤️ を込めて作成

📊 Docker イメージサイズの分析

MCP Optimizer の Docker イメージは、機能とサイズのバランスを取るよう最適化されています。

コンポーネント	サイズ	合計に占める割合	説明
Python パッケージ（/venv）	237.0 MB	42.8%	依存関係を含む仮想環境
システムライブラリ（/usr）	173.2 MB	31.3%	ベース Debian システム＋Python
その他	137.4 MB	24.8%	ベースイメージ、ファイルシステム
設定（/var, /etc）	6.2 MB	1.1%	システム設定
アプリケーションコード（/code）	0.2 MB	0.04%	MCP Optimizer のソースコード

サイズ別の主な依存関係

• OR-Tools：75.0 MB（venv の 27.8%）- 重要な最適化ソルバー（pandas と numpy が必要）
• pandas：45.0 MB（venv の 16.7%）- データ操作のために OR-Tools が必要とします
• NumPy：24.0 MB（venv の 8.9%）- 数値計算のために OR-Tools が必要とします
• PuLP：34.9 MB（venv の 12.9%）- 線形計画法ソルバー
• FastMCP：15.2 MB（venv の 5.6%）- MCP サーバーのフレームワーク
• Pydantic：12.8 MB（venv の 4.7%）- データ検証

依存関係の分析

• コアパッケージはこれ以上削減できません：主要な最適化エンジンである OR-Tools は、必須の依存関係として pandas と numpy の両方を必要とします
• オプションのサンプルを移動：サンプル用の追加パッケージ（streamlit、plotly）は [examples] エクストラに移動しました
• コアへの影響は最小限：サンプルをオプションの依存関係に移動しても、開発やデモでの使用にのみ影響します

イメージの最適化

• 現在の最適化済みサイズ：約 420MB
• コア機能：本番環境での最適化に必要な依存関係をすべて含みます
• サンプルのサポート：追加のデモ機能を利用するには、[examples] エクストラを指定してインストールします
• OR-Tools の制約：依存関係の必須要件により、pandas と numpy は削除できません