Mcp_constrained_optimization

制約付き最適化 MCP サーバー

論理制約と数値制約を伴う組み合わせ最適化問題を解くための汎用 Model Context Protocol（MCP）サーバーです。このサーバーは複数の最適化ソルバーに統一されたインターフェースを提供し、AI アシスタントがさまざまな分野の複雑な最適化問題を解けるようにします。

🚀 特長

• 統一インターフェース：複数の最適化バックエンドに対応する単一の MCP サーバー
• AI 対応：MCP プロトコルを介した AI アシスタントでの利用を想定して設計
• ポートフォリオに特化：ポートフォリオ最適化とリスク管理のための専用ツール
• 拡張可能：新しいソルバーを簡単に追加できるモジュール設計
• 高性能：大規模な問題向けに最適化
• 堅牢：包括的なエラー処理と検証

🛠️ 対応ソルバー

• Z3 - 制約充足問題向け SMT ソルバー
• CVXPY - 凸最適化ソルバー
• HiGHS - 線形計画法および混合整数計画法ソルバー
• OR-Tools - 制約プログラミングソルバー

📦 インストール

# Install the package
pip install constrained-opt-mcp

# Or install from source
git clone https://github.com/your-org/constrained-opt-mcp
cd constrained-opt-mcp
pip install -e .

📐 数学的基礎

最適化理論

Constrained Optimization MCP Server は、さまざまなクラスの最適化問題に対するソリューションを実装しています。

線形計画法（LP）

$$\min_{x} c^T x \quad \text{subject to} \quad Ax \leq b, \quad x \geq 0$$

二次計画法（QP）

$$\min_{x} \frac{1}{2}x^T Q x + c^T x \quad \text{subject to} \quad Ax \leq b, \quad x \geq 0$$

凸最適化

$$\min_{x} f(x) \quad \text{subject to} \quad g_i(x) \leq 0, \quad h_j(x) = 0$$

ここで、$f$ と $g_i$ は凸関数です。

制約充足問題（CSP）

$C_1(x) \land C_2(x) \land \ldots \land C_k(x)$ を満たす $x \in \mathcal{D}$ を求めます。

ポートフォリオ最適化（Markowitz）

$$\max_{w} \mu^T w - \frac{\lambda}{2} w^T \Sigma w \quad \text{subject to} \quad \sum_{i=1}^{n} w_i = 1, \quad w_i \geq 0$$

各変数の意味は次のとおりです。

• $w$：ポートフォリオのウェイト
• $\mu$：期待リターン
• $\Sigma$：共分散行列
• $\lambda$：リスク回避度パラメーター

ソルバーの機能

問題の種類	ソルバー	計算量	数学的形式
制約充足	Z3	NP 完全	論理制約
凸最適化	CVXPY	多項式時間	凸関数
線形計画法	HiGHS	多項式時間	線形制約
制約プログラミング	OR-Tools	NP 完全	離散領域

🚀 クイックスタート

1. サンプルを実行する

# Run individual examples
python examples/nqueens.py
python examples/knapsack.py
python examples/portfolio_optimization.py
python examples/job_shop_scheduling.py
python examples/nurse_scheduling.py
python examples/economic_production_planning.py

# Run interactive notebook
jupyter notebook examples/constrained_optimization_demo.ipynb

2. MCP サーバーを起動する

constrained-opt-mcp

3. AI アシスタントから接続する

MCP 設定にサーバーを追加します。

{
  "mcpServers": {
    "constrained-opt-mcp": {
      "command": "constrained-opt-mcp",
      "args": []
    }
  }
}

4. ツールを使用する

サーバーでは次のツールを利用できます。

• solve_constraint_satisfaction - 論理制約問題を解く
• solve_convex_optimization - 凸最適化問題を解く
• solve_linear_programming - 線形計画問題を解く
• solve_constraint_programming - 制約プログラミング問題を解く
• solve_portfolio_optimization - ポートフォリオ最適化問題を解く

📚 使用例

制約充足問題

# Solve a simple arithmetic constraint problem
variables = [
    {"name": "x", "type": "integer"},
    {"name": "y", "type": "integer"},
]
constraints = [
    "x + y == 10",
    "x - y == 2",
]

# Result: x=6, y=4

ポートフォリオ最適化

# Optimize portfolio allocation
assets = ["Stocks", "Bonds", "Real Estate", "Commodities"]
expected_returns = [0.10, 0.03, 0.07, 0.06]
risk_factors = [0.15, 0.03, 0.12, 0.20]
correlation_matrix = [
    [1.0, 0.2, 0.6, 0.3],
    [0.2, 1.0, 0.1, 0.05],
    [0.6, 0.1, 1.0, 0.25],
    [0.3, 0.05, 0.25, 1.0],
]

# Result: Optimal portfolio weights and performance metrics

線形計画法

# Production planning problem
sense = "maximize"
objective_coeffs = [3.0, 2.0]  # Profit per unit
variables = [
    {"name": "product_a", "lb": 0, "ub": None, "type": "cont"},
    {"name": "product_b", "lb": 0, "ub": None, "type": "cont"},
]
constraint_matrix = [
    [2, 1],  # Labor: 2*A + 1*B <= 100
    [1, 2],  # Material: 1*A + 2*B <= 80
]
constraint_senses = ["<=", "<="]
rhs_values = [100.0, 80.0]

# Result: Optimal production quantities

ポートフォリオの例

• ポートフォリオ最適化 - Markowitz、Black-Litterman、ESG 制約付き最適化などの高度なポートフォリオ最適化戦略
• リスク管理 - VaR 最適化、ストレステスト、ヘッジなどのリスク管理戦略

ポートフォリオ最適化機能の強化

株式ポートフォリオの最適化：

• セクター分散の制約（セクターごとに最大25％）
• 時価総額の制約（大型株、中型株、小型株の配分）
• ESG（環境、社会、ガバナンス）の制約
• 流動性要件と個別ポジションの上限
• 高度な指標を用いたリスク・リターン最適化

マルチアセットポートフォリオの最適化：

• 資産クラスの制約（株式、債券、オルタナティブ、現金）
• 地域別エクスポージャーの上限（先進国市場と新興国市場）
• オルタナティブ投資の制約（コモディティ、不動産、プライベートエクイティ）
• 動的なリバランスとリスク予算の設定
• 取引コストを考慮した複数期間の最適化

高度なリスク指標：

• バリュー・アット・リスク（VaR）と条件付きバリュー・アット・リスク（CVaR）
• 最大ドローダウンとテールリスク
• ファクターエクスポージャー分析とリスク寄与度分析
• ストレステストとシナリオ分析
• 相関リスクと集中リスクの管理

包括的なサンプル

🎯 組合せ最適化

• N-Queens Problem - チェス盤の可視化を用いた、制約充足問題の定番
• Knapsack Problem - パフォーマンス分析を含む0/1ナップサック問題と複数ナップサック問題のバリエーション

🏭 スケジューリングとオペレーション

• Job Shop Scheduling - ガントチャートを用いた複数機械の生産スケジューリング
• Nurse Scheduling - 公平性の制約を伴う複雑な人員スケジューリング

📊 数理経済学と金融

• Portfolio Optimization - Markowitz、Black-Litterman、Risk Parity、ESG制約付き最適化などの高度な戦略
• Economic Production Planning - 在庫管理を伴う複数期間のサプライチェーン最適化

🧮 インタラクティブな学習

• Comprehensive Demo Notebook - あらゆる種類のソルバーと可視化を含む、インタラクティブなJupyterノートブック

🧪 テスト

包括的なテストスイートを実行します：

# Run all tests
pytest

# Run specific test categories
pytest tests/test_z3_solver.py
pytest tests/test_cvxpy_solver.py
pytest tests/test_highs_solver.py
pytest tests/test_ortools_solver.py
pytest tests/test_mcp_server.py

# Run with coverage
pytest --cov=constrained_opt_mcp

📖 ドキュメント

• API Reference - APIドキュメント一式
• Examples - 包括的なサンプルとデモ
• Jupyter Notebook - インタラクティブなデモノートブック
• PDF Documentation - 理論、サンプル、実装の詳細を含む包括的なPDFガイド
• Journal-Style PDF - 文献レビュー、数学的内容、研究成果を含む学術論文形式のドキュメント

🏗️ アーキテクチャ

コアコンポーネント

1. コアモデル (constrained_opt_mcp/core/) - 基底クラスと問題の種類
2. ソルバーモデル (constrained_opt_mcp/models/) - 問題固有のモデル定義
3. ソルバー (constrained_opt_mcp/solvers/) - ソルバーの実装
4. MCP サーバー (constrained_opt_mcp/server/) - MCP サーバーの実装
5. サンプル (constrained_opt_mcp/examples/) - 使用例とデモ

対応する問題の種類

問題の種類	ソルバー	ユースケース
制約充足問題	Z3	ロジックパズル、検証、計画
凸最適化	CVXPY	ポートフォリオ最適化、機械学習
線形計画法	HiGHS	生産計画、リソース配分
制約プログラミング	OR-Tools	スケジューリング、割り当て、経路探索
ポートフォリオ最適化	複数	リスク管理、ポートフォリオ構築

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. 新しい機能のテストを追加します
5. テストスイートを実行します
6. プルリクエストを送信します

📄 ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🆘 サポート

質問、問題、貢献については、以下をご確認ください。

1. ドキュメントを確認します
2. 既存のイシューを検索します
3. 新しいイシューを作成します
4. ディスカッションに参加します

📈 変更履歴

バージョン 1.0.0

• 初回リリース
• Z3、CVXPY、HiGHS、OR-Tools に対応
• ポートフォリオ最適化の例
• 包括的なテストスイート
• MCP サーバーの実装