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

Core Models (constrained_opt_mcp/core/) - Base classes and problem types
Solver Models (constrained_opt_mcp/models/) - Problem-specific model definitions
Solvers (constrained_opt_mcp/solvers/) - Solver implementations
MCP Server (constrained_opt_mcp/server/) - MCP server implementation
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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:

Check the documentation
Search existing issues
Create a new issue
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