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

# 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

📚 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

🤝 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