MCP Constrained Optimization

🚀 Constrained Optimization MCP Server

A general-purpose Model Context Protocol (MCP) server designed to solve combinatorial optimization problems with logical and numerical constraints. It offers a unified interface to multiple optimization solvers, enabling AI assistants to tackle complex optimization problems across various domains.

✨ Features

• Unified Interface: A single MCP server for multiple optimization backends.
• AI-Ready: Designed for use with AI assistants via the MCP protocol.
• Portfolio Focus: Specialized tools for portfolio optimization and risk management.
• Extensible: Modular design for easy addition of new solvers.
• High Performance: Optimized for large-scale problems.
• Robust: Comprehensive error handling and validation.

🛠️ Supported Solvers

• Z3 - SMT solver for constraint satisfaction problems.
• CVXPY - Convex optimization solver.
• HiGHS - Linear and mixed-integer programming solver.
• OR-Tools - Constraint programming solver.

📦 Installation

# 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 .

📐 Mathematical Foundations

Optimization Theory

The Constrained Optimization MCP Server implements solutions for various classes of optimization problems:

Linear Programming (LP)

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

Quadratic Programming (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$$

Convex Optimization

$$\min_{x} f(x) \quad \text{subject to} \quad g_i(x) \leq 0, \quad h_j(x) = 0$$ Where $f$ and $g_i$ are convex functions.

Constraint Satisfaction Problems (CSP)

Find $x \in \mathcal{D}$ such that $C_1(x) \land C_2(x) \land \ldots \land C_k(x)$

Portfolio Optimization (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$$ Where:

• $w$: portfolio weights.
• $\mu$: expected returns.
• $\Sigma$: covariance matrix.
• $\lambda$: risk aversion parameter.

Solver Capabilities

🚀 Quick Start

1. Run Examples

# 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. Start the MCP Server

constrained-opt-mcp

3. Connect from AI Assistant

Add the server to your MCP configuration:

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

4. Use the Tools

The server provides the following tools:

• solve_constraint_satisfaction - Solve logical constraint problems.
• solve_convex_optimization - Solve convex optimization problems.
• solve_linear_programming - Solve linear programming problems.
• solve_constraint_programming - Solve constraint programming problems.
• solve_portfolio_optimization - Solve portfolio optimization problems.

💻 Usage Examples

Basic Usage

Constraint Satisfaction Problem

# 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

Portfolio Optimization

# 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

Linear Programming

# 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

Advanced Usage

Portfolio Examples

• Portfolio Optimization - Advanced portfolio optimization strategies including Markowitz, Black-Litterman, and ESG-constrained optimization.
• Risk Management - Risk management strategies including VaR optimization, stress testing, and hedging.

Enhanced Portfolio Optimization Features

Equity Portfolio Optimization:

• Sector diversification constraints (max 25% per sector).
• Market cap constraints (large, mid, small cap allocations).
• ESG (Environmental, Social, Governance) constraints.
• Liquidity requirements and individual position limits.
• Risk-return optimization with advanced metrics.

Multi-Asset Portfolio Optimization:

• Asset class constraints (equity, fixed income, alternatives, cash).
• Regional exposure limits (developed vs emerging markets).
• Alternative investment constraints (commodities, real estate, private equity).
• Dynamic rebalancing and risk budgeting.
• Multi-period optimization with transaction costs.

Advanced Risk Metrics:

• Value at Risk (VaR) and Conditional VaR (CVaR).
• Maximum Drawdown and Tail Risk.
• Factor exposure analysis and risk attribution.
• Stress testing and scenario analysis.
• Correlation and concentration risk management.

Comprehensive Examples

🎯 Combinatorial Optimization

• N-Queens Problem - Classic constraint satisfaction with chessboard visualization.
• Knapsack Problem - 0/1 and multiple knapsack variants with performance analysis.

🏭 Scheduling & Operations

• Job Shop Scheduling - Multi-machine production scheduling with Gantt charts.
• Nurse Scheduling - Complex workforce scheduling with fairness constraints.

📊 Quantitative Economics & Finance

• Portfolio Optimization - Advanced strategies including Markowitz, Black-Litterman, Risk Parity, and ESG-constrained optimization.
• Economic Production Planning - Multi-period supply chain optimization with inventory management.

🧮 Interactive Learning

• Comprehensive Demo Notebook - Interactive Jupyter notebook with all solver types and visualizations.

🧪 Testing

Run the comprehensive test suite:

# 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

📚 Documentation

• API Reference - Complete API documentation.
• Examples - Comprehensive examples and demos.
• Jupyter Notebook - Interactive demo notebook.
• PDF Documentation - Comprehensive PDF guide with theory, examples, and implementation details.
• Journal-Style PDF - Academic paper format with literature review, mathematics, and research contributions.

🔧 Technical Details

Architecture

Core Components

1. Core Models (constrained_opt_mcp/core/) - Base classes and problem types.
2. Solver Models (constrained_opt_mcp/models/) - Problem-specific model definitions.
3. Solvers (constrained_opt_mcp/solvers/) - Solver implementations.
4. MCP Server (constrained_opt_mcp/server/) - MCP server implementation.
5. Examples (constrained_opt_mcp/examples/) - Usage examples and demos.

Supported Problem Types

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests for new functionality.
5. Run the test suite.
6. Submit a pull request.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

🆘 Support

For questions, issues, or contributions, please:

1. Check the documentation.
2. Search existing issues.
3. Create a new issue.
4. Join our discussions.

📈 Changelog

Version 1.0.0

• Initial release.
• Support for Z3, CVXPY, HiGHS, and OR-Tools.
• Portfolio optimization examples.
• Comprehensive test suite.
• MCP server implementation.