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

📐 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

2. Start the MCP Server

3. Connect from AI Assistant

Add the server to your MCP configuration:

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

Portfolio Optimization

Linear Programming

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:

📖 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