constrained-opt-mcp 1.0.1
General Purpose MCP Server for Constrained Optimization - AI agents for optimization tasks such as portfolio optimization, scheduling, and combinatorial problems
License: Apache-2.0
Requires Python: >=3.10
Keywords: ai-agents, combinatorial-optimization, constraint-satisfaction, financial-optimization, linear-programming, mathematical-optimization, mcp, model-context-protocol, operations-research, optimization, portfolio-optimization, scheduling

<p align="center">
    <img src=".github/logo.png" width="500px" alt="Constrained Optimization MCP Server">
</p>

# Constrained Optimization MCP Server

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

## 🚀 Features

- **Unified Interface**: Single MCP server for multiple optimization backends
- **AI-Ready**: Designed for use with AI assistants through 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`](https://github.com/Z3Prover/z3) - SMT solver for constraint satisfaction problems
* [`CVXPY`](https://www.cvxpy.org/) - Convex optimization solver
* [`HiGHS`](https://highs.dev/) - Linear and mixed-integer programming solver
* [`OR-Tools`](https://developers.google.com/optimization) - Constraint programming solver

## 📦 Installation

```bash
# 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

| Problem Type | Solver | Complexity | Mathematical Form |
|--------------|--------|------------|-------------------|
| Constraint Satisfaction | Z3 | NP-Complete | Logical constraints |
| Convex Optimization | CVXPY | Polynomial | Convex functions |
| Linear Programming | HiGHS | Polynomial | Linear constraints |
| Constraint Programming | OR-Tools | NP-Complete | Discrete domains |

## 🚀 Quick Start

### 1. Run Examples

```bash
# 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

```bash
constrained-opt-mcp
```

### 3. Connect from AI Assistant

Add the server to your MCP configuration:

```json
{
  "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

## 📚 Examples

### Constraint Satisfaction Problem

```python
# 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

```python
# 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

```python
# 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
```

### Portfolio Examples

- **[Portfolio Optimization](constrained_opt_mcp/examples/financial/portfolio_optimization.py)** - Advanced portfolio optimization strategies including Markowitz, Black-Litterman, and ESG-constrained optimization
- **[Risk Management](constrained_opt_mcp/examples/financial/risk_management.py)** - 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](examples/nqueens.py)** - Classic constraint satisfaction with chessboard visualization
- **[Knapsack Problem](examples/knapsack.py)** - 0/1 and multiple knapsack variants with performance analysis

#### 🏭 **Scheduling & Operations**
- **[Job Shop Scheduling](examples/job_shop_scheduling.py)** - Multi-machine production scheduling with Gantt charts
- **[Nurse Scheduling](examples/nurse_scheduling.py)** - Complex workforce scheduling with fairness constraints

#### 📊 **Quantitative Economics & Finance**
- **[Portfolio Optimization](examples/portfolio_optimization.py)** - Advanced strategies including Markowitz, Black-Litterman, Risk Parity, and ESG-constrained optimization
- **[Economic Production Planning](examples/economic_production_planning.py)** - Multi-period supply chain optimization with inventory management

#### 🧮 **Interactive Learning**
- **[Comprehensive Demo Notebook](examples/constrained_optimization_demo.ipynb)** - Interactive Jupyter notebook with all solver types and visualizations

## 🧪 Testing

Run the comprehensive test suite:

```bash
# 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](docs/README.md)** - Complete API documentation
- **[Examples](examples/)** - Comprehensive examples and demos
- **[Jupyter Notebook](examples/constrained_optimization_demo.ipynb)** - Interactive demo notebook
- **[PDF Documentation](docs/constrained_optimization_package.pdf)** - Comprehensive PDF guide with theory, examples, and implementation details
- **[Journal-Style PDF](docs/constrained_optimization_journal.pdf)** - Academic paper format with literature review, mathematics, and research contributions

## 🏗️ 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

| Problem Type | Solver | Use Cases |
|--------------|--------|-----------|
| Constraint Satisfaction | Z3 | Logic puzzles, verification, planning |
| Convex Optimization | CVXPY | Portfolio optimization, machine learning |
| Linear Programming | HiGHS | Production planning, resource allocation |
| Constraint Programming | OR-Tools | Scheduling, assignment, routing |
| Portfolio Optimization | Multiple | Risk management, portfolio construction |

## 🤝 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](LICENSE) file for details.

## 🆘 Support

For questions, issues, or contributions, please:

1. Check the [documentation](docs/)
2. Search [existing issues](https://github.com/your-org/constrained-opt-mcp/issues)
3. Create a [new issue](https://github.com/your-org/constrained-opt-mcp/issues/new)
4. Join our [discussions](https://github.com/your-org/constrained-opt-mcp/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