Mcp_constrained_optimization

约束优化 MCP 服务

一款通用的模型上下文协议（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 .

📐 数学基础

优化理论

约束优化 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）

求解满足 $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-Complete	逻辑约束
凸优化	CVXPY	Polynomial	凸函数
线性规划	HiGHS	Polynomial	线性约束
约束规划	OR-Tools	NP-Complete	离散域

🚀 快速开始

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 皇后问题 - 经典约束满足问题，带棋盘可视化
• 背包问题 - 0/1 背包和多重背包变体，带性能分析

🏭 调度与运营

• 作业车间调度 - 多机器生产调度，带甘特图
• 护士排班 - 带公平性约束的复杂人员排班

📊 定量经济学与金融

• 投资组合优化 - 高级策略，包括 Markowitz、Black-Litterman、风险平价和 ESG 约束优化
• 经济生产计划 - 带库存管理的多期供应链优化

🧮 交互式学习

• 综合演示 Notebook - 交互式 Jupyter Notebook，包含所有求解器类型和可视化

🧪 测试

运行综合测试套件：

# 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 参考 - 完整的 API 文档
• 示例 - 综合示例和演示
• Jupyter Notebook - 交互式演示 Notebook
• PDF 文档 - 综合 PDF 指南，包含理论、示例和实现细节
• 期刊风格 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. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交 Pull Request

📄 许可证

本项目采用 Apache License 2.0 许可。详情请参阅 LICENSE 文件。

🆘 支持

如有疑问、问题或贡献，请：

1. 查看文档
2. 搜索现有问题
3. 创建新问题
4. 加入我们的讨论

📈 更新日志

版本 1.0.0

• 首次发布
• 支持 Z3、CVXPY、HiGHS 和 OR-Tools
• 投资组合优化示例
• 完整的测试套件
• MCP 服务实现