<p align="center">

</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 - 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

| 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

# 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

📚 Examples

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: 2A + 1B <= 100
    [1, 2],  # Material: 1A + 2B <= 80
]
constraint_senses = ["<=", "<="]
rhs_values = [100.0, 80.0]
Result: Optimal production quantities

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

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