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服务器实现