MCP Constrained Optimization

🚀 約束優化MCP服務器

這是一個通用的模型上下文協議（MCP）服務器，用於解決帶有邏輯和數值約束的組合優化問題。該服務器為多個優化求解器提供了統一接口，使AI助手能夠解決跨多個領域的複雜優化問題。

🚀 快速開始

1. 運行示例

# 運行單個示例
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

# 運行交互式筆記本
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 - 解決投資組合優化問題

✨ 主要特性

• 統一接口：單個MCP服務器支持多個優化後端
• 適配AI：設計用於通過MCP協議與AI助手配合使用
• 專注投資組合：提供專門用於投資組合優化和風險管理的工具
• 可擴展：模塊化設計，便於添加新的求解器
• 高性能：針對大規模問題進行了優化
• 健壯性：具備全面的錯誤處理和驗證機制

📦 安裝指南

# 安裝軟件包
pip install constrained-opt-mcp

# 或者從源代碼安裝
git clone https://github.com/your-org/constrained-opt-mcp
cd constrained-opt-mcp
pip install -e .

💻 使用示例

基礎用法

約束滿足問題

# 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

高級用法

投資組合示例

• 投資組合優化 - 高級投資組合優化策略，包括馬科維茨、布萊克 - 利特曼和ESG約束優化
• 風險管理 - 風險管理策略，包括風險價值（VaR）優化、壓力測試和套期保值

增強型投資組合優化特性

股票投資組合優化：

• 行業多元化約束（每個行業最高25%）
• 市值約束（大盤、中盤、小盤股配置）
• ESG（環境、社會、治理）約束
• 流動性要求和單個頭寸限制
• 使用高級指標進行風險 - 回報優化

多資產投資組合優化：

• 資產類別約束（股票、固定收益、另類投資、現金）
• 區域敞口限制（發達市場與新興市場）
• 另類投資約束（大宗商品、房地產、私募股權）
• 動態再平衡和風險預算
• 考慮交易成本的多期優化

高級風險指標：

• 風險價值（VaR）和條件風險價值（CVaR）
• 最大回撤和尾部風險
• 因子暴露分析和風險歸因
• 壓力測試和情景分析
• 相關性和集中風險管理

綜合示例

🎯 組合優化

• N皇后問題 - 經典約束滿足問題，帶有棋盤可視化
• 揹包問題 - 0/1和多揹包變體，帶有性能分析

🏭 調度與運營

• 作業車間調度 - 多機器生產調度，帶有甘特圖
• 護士調度 - 複雜的勞動力調度，帶有公平性約束

📊 量化經濟與金融

• 投資組合優化 - 高級策略，包括馬科維茨、布萊克 - 利特曼、風險平價和ESG約束優化
• 經濟生產計劃 - 考慮庫存管理的多期供應鏈優化

🧮 交互式學習

• 綜合演示筆記本 - 交互式Jupyter筆記本，涵蓋所有求解器類型和可視化

📚 詳細文檔

• API參考 - 完整的API文檔
• 示例 - 全面的示例和演示
• Jupyter筆記本 - 交互式演示筆記本
• PDF文檔 - 全面的PDF指南，包含理論、示例和實現細節
• 期刊風格PDF - 學術論文格式，包含文獻綜述、數學原理和研究貢獻

🔧 技術細節

數學基礎

優化理論

約束優化MCP服務器實現了各種優化問題的解決方案：

線性規劃（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）

找到 $x \in \mathcal{D}$ 使得 $C_1(x) \land C_2(x) \land \ldots \land C_k(x)$

投資組合優化（馬科維茨）

$$\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$：風險厭惡參數

求解器能力

架構

核心組件

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/) - 使用示例和演示

支持的問題類型

🧪 測試

運行全面的測試套件：

# 運行所有測試
pytest

# 運行特定測試類別
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

# 運行測試並統計覆蓋率
pytest --cov=constrained_opt_mcp

🤝 貢獻代碼

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 運行測試套件
6. 提交拉取請求

📄 許可證

本項目採用Apache License 2.0許可協議。有關詳細信息，請參閱 LICENSE 文件。

🆘 支持

如果您有問題、發現問題或想要貢獻代碼，請：

1. 查看 文檔
2. 搜索 現有問題
3. 創建 新問題
4. 加入我們的 討論

📈 變更日誌

版本1.0.0

• 初始版本發佈
• 支持Z3、CVXPY、HiGHS和OR-Tools求解器
• 提供投資組合優化示例
• 全面的測試套件
• MCP服務器實現