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