MCP Ortools

🚀 MCP-ORTools: Model Context Protocol Server Implementation with Google OR-Tools

MCP-ORTools combines Google's OR-Tools constraint programming solver with large language models. It's designed to work with large language models through the Model Context Protocol, enabling AI models to:

• Submit and validate constraint models.
• Set model parameters.
• Solve constraint satisfaction and optimization problems.
• Obtain and analyze solutions.

🚀 Quick Start

MCP-ORTools integrates Google's OR-Tools constraint programming solver with large language models via the Model Context Protocol. This integration empowers AI models to perform a series of operations related to constraint models.

📦 Installation

1. Install the Package

pip install git+https://github.com/Jacck/mcp-ortools.git

2. Configure Claude Desktop

Create a configuration file at %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ortools": {
      "command": "python",
      "args": ["-m", "mcp_ortools.server"]
    }
  }
}

📚 Documentation

Model Specification

The model is specified in JSON format and consists of three main parts:

• variables: Define variables and their domains.
• constraints: List constraints using OR-Tools method syntax.
• objective: An optional optimization objective.

Constraint Syntax

Constraints must use OR-Tools method syntax:

• .__le__() for less than or equal to (<=).
• .__ge__() for greater than or equal to (>=).
• .__eq__() for equal to (==).
• .__ne__() for not equal to (!=).

💻 Usage Examples

Basic Usage

Simple Optimization Model

{
    "variables": [
        {"name": "x", "domain": [0, 10]},
        {"name": "y", "domain": [0, 10]}
    ],
    "constraints": [
        "(x + y).__le__(15)",
        "x.__ge__(2 * y)"
    ],
    "objective": {
        "expression": "40 * x + 100 * y",
        "maximize": true
    }
}

Advanced Usage

Knapsack Problem

Example: Select items with values [3,1,2,1] and weights [2,2,1,1], with a total weight limit of 2.

{
    "variables": [
        {"name": "p0", "domain": [0, 1]},
        {"name": "p1", "domain": [0, 1]},
        {"name": "p2", "domain": [0, 1]},
        {"name": "p3", "domain": [0, 1]}
    ],
    "constraints": [
        "(2*p0 + 2*p1 + p2 + p3).__le__(2)"
    ],
    "objective": {
        "expression": "3*p0 + p1 + 2*p2 + p3",
        "maximize": true
    }
}

Additional Constraint Example

{
    "constraints": [
        "p0.__eq__(1)",         // Item p0 must be selected
        "p1.__ne__(p2)",        // p1 and p2 cannot be selected simultaneously
        "(p2 + p3).__ge__(1)"   // At least one of p2 or p3 must be selected
    ]
}

✨ Features

• Full support for the OR-Tools CP-SAT solver.
• JSON-based model specification.
• Support for:
  • Integer and boolean variables (domain: [min, max]).
  • Linear constraints using OR-Tools method syntax.
  • Linear optimization objectives.
  • Timeouts and solver parameters.
  • Binary constraints and relationships.
  • Portfolio selection problems.
  • Knapsack problems.

Operations Supported in Constraints

• Basic arithmetic: +, -, *
• Comparison: .le(), .ge(), .eq(), .ne()
• Linear combinations of variables.
• Binary logic through constraint combinations.

🔧 Technical Details

Development

To set up the development environment:

git clone https://github.com/Jacck/mcp-ortools.git
cd mcp-ortools

Model Context Protocol (MCP)

Definition

The Model Context Protocol (MCP) is a set of interfaces and methods for defining and managing context information between different components. In this project, MCP is used to transfer and synchronize context data between the constraint solver and other AI components (such as language models).

Key Features

• Define Context: Clearly define the structure and content of the context.
• Interface Standardization: Provide a unified interface for different components.
• Data Management: Support the storage, retrieval, and update of context data.
• Version Control: Allow the management and tracking of different versions of the context.

Implementation Details

In MCP-ORTools, the context information mainly includes the following:

• Variable Information: Names, types, and domains of all problem variables.
• Constraint Information: Description of all constraint conditions related to the problem.
• Objective Function: Definition of the objective expression for the optimization problem.
• Solution Status: Tracking of the current solution process status, such as whether it's being solved or if there's a solution.

Usage Example

from mcp import ModelContext

# Create a context instance
context = ModelContext()

# Add variables
context.add_variable("x", domain=[0, 10])
context.add_variable("y", domain=[0, 10])

# Add constraints
context.add_constraint("(x + y).__le__(15)")
context.add_constraint("x.__ge__(2 * y)")

# Set the objective function
context.set_objective("40 * x + 100 * y", maximize=True)

# Get context information
print(context.variables)  # Output variable information
print(context.constraints)  # Output constraint information
print(context.objective)  # Output objective function information

Extension and Customization

MCP offers high extensibility and customization, allowing users to add custom components or extend functionality according to specific needs. For example:

• Custom Variable Types: Create new variable types by inheriting the Variable class and overriding its methods.
• Custom Constraint Types: Define new constraint types by inheriting the Constraint class.
• Plugin Support: MCP supports a plugin mechanism, allowing users to dynamically load and use additional features.

Documentation and Resources

• Official Documentation: Provides detailed API documentation and usage guides.
• Example Code: Multiple examples demonstrating how to use MCP in real-world scenarios.
• Developer Forum: A community platform for communicating with the development team and other users.