MCP Optimizer

🚀 Mathematical Optimization MCP Server with PuLP and OR-Tools support

📖 Quick Links: 🚀 Quick Start | 🔧 macOS Troubleshooting | 📊 Examples | 🎯 Features

🚀 Quick Start

Recommended Installation Methods (by Priority)

1. 🐳 Docker (Recommended) - Cross-platform

Most stable method with full functionality

bash

# Run with STDIO transport (for MCP clients)
docker run --rm -i ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Run with SSE transport (for remote clients)
docker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \
  ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Check SSE endpoint
curl -i http://localhost:8000/sse

2. 📦 pip + venv - Cross-platform

Standard approach

bash

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate  # Windows

# Install mcp-optimizer
pip install mcp-optimizer

# For SSE issues, use stable dependency versions:
# pip install "mcp-optimizer[stable]"

# Run (STDIO mode recommended)
mcp-optimizer --transport stdio

3. 🚀 uvx - Linux/Windows (full), macOS (partially)

bash

# Linux/Windows - works out of the box
uvx mcp-optimizer

# macOS - requires Python 3.12
uvx --python python3.12 mcp-optimizer

# STDIO mode recommended
uvx mcp-optimizer --transport stdio

macOS users: If you encounter OR-Tools related errors, see 🔧 macOS uvx Troubleshooting section for automated fix scripts.

🍎 macOS Specifics

OR-Tools support:

uvx: PuLP only (limited functionality)
pip: full OR-Tools support
Docker: full OR-Tools support

For full OR-Tools support via pip:

bash

# Install OR-Tools via Homebrew
brew install or-tools

# Then install mcp-optimizer
pip install "mcp-optimizer[stable]"

Transport Mode Recommendations

Installation Method	Recommended Transport	Why
Docker	SSE	Full stability
pip + venv	STDIO	Avoids dependency issues with newer versions
uvx	STDIO	Maximum compatibility

Integration with LLM Clients

Claude Desktop Integration

Option 1: Using Docker (Recommended)

1. Install Claude Desktop from claude.ai

2. Pull the Docker image:

bash

docker pull ghcr.io/dmitryanchikov/mcp-optimizer:latest

3. Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/dmitryanchikov/mcp-optimizer:latest",
        "python", "main.py"
      ]
    }
  }
}

4. Restart Claude Desktop and look for the 🔨 tools icon

Option 2: Using pip + venv

bash

# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install mcp-optimizer

Then add to your Claude Desktop config:

json

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "mcp-optimizer"
    }
  }
}

Option 3: Using uvx

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "mcp-optimizer": {
      "command": "uvx",
      "args": ["mcp-optimizer"]
    }
  }
}

*Note: On macOS, uvx provides limited functionality (PuLP solver only) or see 🔧 macOS uvx Troubleshooting*

Advanced Docker Setup (for remote MCP clients)

bash

# Run SSE server on port 8000 (uses environment variable)
docker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \
  ghcr.io/dmitryanchikov/mcp-optimizer:latest

# Or with CLI argument and custom port
docker run -d -p 9000:9000 ghcr.io/dmitryanchikov/mcp-optimizer:latest \
  python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000

# Check server status
docker logs 

# Verify SSE endpoint (should show event stream)
curl -i http://localhost:8000/sse

SSE Endpoint: http://localhost:8000/sse (Server-Sent Events for MCP communication)

Cursor Integration

1. Install the MCP extension in Cursor

2. Add mcp-optimizer to your workspace settings (Docker recommended):

json

{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/dmitryanchikov/mcp-optimizer:latest",
        "python", "main.py"
      ]
    }
  }
}

Alternative configurations:

json

// Using pip installation
{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "mcp-optimizer"
    }
  }
}

// Using uvx (limited functionality on macOS)
{
  "mcp.servers": {
    "mcp-optimizer": {
      "command": "uvx",
      "args": ["mcp-optimizer"]
    }
  }
}

Other LLM Clients

For other MCP-compatible clients (Continue, Cody, etc.), use similar configuration patterns. Recommended priority:

1. Docker (maximum stability across platforms)

2. pip + venv (standard Python approach)

3. uvx (quick testing, limited on macOS)

Advanced Installation Options

Local Development

bash

# Clone the repository
git clone https://github.com/dmitryanchikov/mcp-optimizer.git
cd mcp-optimizer

# Install dependencies with uv
uv sync --extra dev

# Run the server
uv run python main.py

Local Package Build and Run

For testing and development, you can build the package locally and run it with uvx:

bash

# Build the package locally
uv build

# Run with uvx from local wheel file
uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer

# Or run with help to see available options
uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer --help

# Test the local package with a simple MCP message
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer

Note: The local build creates both wheel (.whl) and source distribution (.tar.gz) files in the dist/ directory. The wheel file is recommended for uvx installation as it's faster and doesn't require compilation.

Docker with Custom Configuration

bash

# Build locally with optimization
git clone https://github.com/dmitryanchikov/mcp-optimizer.git
cd mcp-optimizer
docker build -t mcp-optimizer:optimized .
docker run -p 8000:8000 mcp-optimizer:optimized

# Check optimized image size (398MB vs 1.03GB original - 61% reduction!)
docker images mcp-optimizer:optimized

# Test the optimized image
./scripts/test_docker_optimization.sh

Standalone Server Commands

bash

# Run directly with uvx (no installation needed)
uvx mcp-optimizer

# Or run specific commands
uvx mcp-optimizer --help

# With pip installation
mcp-optimizer

# Or run with Python module (use main.py for stdio mode)
python main.py

Transport Modes

MCP Optimizer supports two MCP transport protocols:

STDIO: Standard input/output for direct MCP client integration (Claude Desktop, Cursor, etc.)
SSE: Server-Sent Events over HTTP for web-based MCP clients and remote integrations

STDIO Transport (Default - for MCP clients like Claude Desktop)

bash

# Default STDIO mode for MCP protocol
uvx mcp-optimizer
# or
uvx mcp-optimizer --transport stdio
# or
uv run python -m mcp_optimizer.main --transport stdio
# or
python main.py

SSE Transport (for remote MCP clients)

bash

# SSE mode for remote MCP clients (default port 8000)
uvx mcp-optimizer --transport sse
# or
uv run python -m mcp_optimizer.main --transport sse

# Custom host and port
uvx mcp-optimizer --transport sse --host 0.0.0.0 --port 9000
# or
uv run python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000

# With debug mode
uvx mcp-optimizer --transport sse --debug --log-level DEBUG

Available CLI Options

bash

# Show all available options
uvx mcp-optimizer --help

# Options:
#   --transport {stdio,sse}    MCP transport protocol (default: stdio)
#   --port PORT               Port for SSE transport (default: 8000)
#   --host HOST               Host for SSE transport (default: 127.0.0.1)
#   --debug                   Enable debug mode
#   --reload                  Enable auto-reload for development
#   --log-level {DEBUG,INFO,WARNING,ERROR}  Logging level (default: INFO)
#
# Environment Variables:
#   TRANSPORT_MODE={stdio,sse}  Override transport mode
#   SERVER_HOST=0.0.0.0        Override server host
#   SERVER_PORT=8000           Override server port

🔧 Platform Compatibility & Troubleshooting

macOS Compatibility

✅ Full Functionality:

Homebrew + pip: brew install or-tools && pip install mcp-optimizer
Virtual environments: python -m venv venv && source venv/bin/activate && pip install ortools mcp-optimizer
Docker: Full OR-Tools support in containers

⚠️ Limited Functionality:

uvx (isolated environments): Only PuLP solver available due to OR-Tools native library paths
Fallback behavior: Automatically switches to PuLP when OR-Tools unavailable

Common Issues & Solutions:

1. OR-Tools "Library not loaded" error:

bash

# Solution: Install via Homebrew
   brew install or-tools
   # Then use regular pip/venv instead of uvx

2. uvx shows OR-Tools warnings:

bash

WARNING: OR-Tools not available: No module named 'ortools'

This is expected - uvx provides fallback functionality with PuLP solver.

3. Best practices for macOS:

Use Docker for production deployments
Use Homebrew + pip for development
Use uvx for quick testing (limited functionality)

Linux/Windows Compatibility

✅ Full Functionality:

uvx: Works out of the box with OR-Tools
pip: Standard installation
Docker: Recommended for production

Solver Availability by Platform

Platform	uvx	pip	Docker
macOS	PuLP only	✅ Full	✅ Full
Linux	✅ Full	✅ Full	✅ Full
Windows	✅ Full	✅ Full	✅ Full

Solver Features:

OR-Tools: Advanced algorithms (CP-SAT, routing, scheduling)
PuLP: Basic linear programming, reliable fallback

🔧 macOS uvx Troubleshooting

Problem: OR-Tools Library Issues with uvx

Common Error Messages:

code

Library not loaded: /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib
ImportError: No module named 'ortools'
WARNING: OR-Tools not available

Root Cause: OR-Tools binary wheels contain hardcoded library paths that fail in uvx isolated environments. This is a macOS-specific issue due to how uvx isolates dependencies.

📊 Functionality Impact by Installation Method

✅ Available with uvx + fallback (PuLP solver only):

Linear Programming - Basic optimization, simplex method
Financial Optimization - Portfolio optimization, risk management
Production Planning - Resource allocation, inventory management

❌ Lost with uvx (requires OR-Tools):

Assignment Problems - Hungarian algorithm, transportation problems
Integer Programming - Mixed-integer, binary programming (SCIP/CBC)
Knapsack Problems - Discrete optimization, multiple variants
Vehicle Routing - TSP, CVRP, time windows (constraint programming)
Job Scheduling - CP-SAT solver, resource planning

🛠️ Solutions (in order of preference)

1. Automated Fix Script (Recommended)

bash

# Smart adaptive script - no hardcoded versions!
# Automatically detects your system libraries and Python versions
./scripts/fix_macos_uvx.sh

# Then uvx works with full functionality
uvx mcp-optimizer --transport stdio

2. Manual Fix

bash

# Install system dependencies
brew install or-tools scip

# Create symlink for hardcoded path
sudo mkdir -p /Users/corentinl/work/stable/temp_python3.13/lib/
sudo ln -sf /opt/homebrew/lib/libscip.9.2.dylib /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib

# Test fix
uvx mcp-optimizer --help

3. Use pip (Always Works)

bash

# Install dependencies first
brew install or-tools

# Install package
pip install mcp-optimizer
mcp-optimizer

4. Use Docker (Production Ready)

bash

docker run -p 8000:8000 mcp-optimizer

🎯 Features

Supported Optimization Problem Types:

Linear Programming - Maximize/minimize linear objective functions
Assignment Problems - Optimal resource allocation using Hungarian algorithm
Transportation Problems - Logistics and supply chain optimization
Knapsack Problems - Optimal item selection (0-1, bounded, unbounded)
Routing Problems - TSP and VRP with time windows
Scheduling Problems - Job and shift scheduling
Integer Programming - Discrete optimization problems
Financial Optimization - Portfolio optimization and risk management
Production Planning - Multi-period production planning

Testing

Automated Test Scripts

Quick Testing:

bash

# Test local package build and functionality
./scripts/test_local_package.sh

# Test Docker container build and functionality  
./scripts/test_docker_container.sh

# Run comprehensive test suite (both package and Docker)
./scripts/test_all.sh

# Run only specific tests
./scripts/test_all.sh --skip-docker    # Skip Docker tests
./scripts/test_all.sh --skip-package   # Skip package tests

Manual Testing:

bash

# Run simple functionality tests
uv run python tests/test_integration/comprehensive_test.py

# Run comprehensive integration tests
uv run python tests/test_integration/comprehensive_test.py

# Run all unit tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src/mcp_optimizer --cov-report=html

Test Scripts Features:

✅ Local Package Testing: Build, STDIO/SSE modes, CLI functionality
✅ Docker Container Testing: Image build, environment variables, health checks
✅ Comprehensive Suite: Parallel execution with detailed reporting
✅ Automatic Cleanup: Processes and containers cleaned up after tests
✅ Cross-Platform: Works on macOS, Linux (requires Docker for container tests)

Requirements:

For local tests: uv, curl, lsof, gtimeout/timeout
For Docker tests: docker + local requirements
macOS: brew install coreutils (for gtimeout)

CI/CD Integration:

yaml

# GitHub Actions example
- name: Test Package
  run: ./scripts/test_local_package.sh
- name: Test Docker
  run: ./scripts/test_docker_container.sh

📊 Usage Examples

Linear Programming

python

from mcp_optimizer.tools.linear_programming import solve_linear_program

# Maximize 3x + 2y subject to:
# x + y = 0

objective = {"sense": "maximize", "coefficients": {"x": 3, "y": 2}}
variables = {
    "x": {"type": "continuous", "lower": 0},
    "y": {"type": "continuous", "lower": 0}
}
constraints = [
    {"expression": {"x": 1, "y": 1}, "operator": " 🔒 **Secure Detection**: Uses hybrid approach combining GitHub branch protection with automated release detection. See [Release Process](.github/RELEASE_PROCESS.md) for details.

### Automated Release Pipeline
The CI/CD pipeline automatically handles:
- ✅ **Release Candidates**: Built from `release/*` branches
- ✅ **Production Releases**: Triggered by version tags on `main`
- ✅ **PyPI Publishing**: Automatic on tag creation
- ✅ **Docker Images**: Multi-architecture builds
- ✅ **GitHub Releases**: With artifacts and release notes

### CI/CD Pipeline
The GitHub Actions workflow automatically:
- ✅ Runs tests on Python 3.11 and 3.12
- ✅ Performs security scanning
- ✅ Builds and pushes Docker images
- ✅ Publishes to PyPI on tag creation
- ✅ Creates GitHub releases

### Requirements for PyPI Publication
- Set `PYPI_API_TOKEN` secret in GitHub repository
- Ensure all tests pass
- Follow semantic versioning

## 🛠️ Development Tools

### Debug Tools
Use the debug script to inspect MCP server structure:

Run debug tools to check server structure

uv run python scripts/debug_tools.py

This will show:

- Available MCP tools

- Tool types and attributes

- Server configuration

code

### Comprehensive Testing
Run the full integration test suite:

Run comprehensive tests

uv run python tests/test_integration/comprehensive_test.py

This tests:

- All optimization tools (9 categories)

- Server health and functionality

- Performance benchmarks

- End-to-end workflows

code

### Docker Build Instructions

#### Image Details
- **Base**: Python 3.12 Slim (Debian-based)
- **Size**: ~649MB (optimized with multi-stage builds)
- **Architecture**: Multi-platform support (x86_64, ARM64)
- **Security**: Non-root user, minimal dependencies
- **Performance**: Optimized Python bytecode, cleaned build artifacts

#### Local Build Commands

Standard build

docker build -t mcp-optimizer:latest .

Build with development dependencies

docker build --build-arg ENV=development -t mcp-optimizer:dev .

Build with cache mount for faster rebuilds

docker build --mount=type=cache,target=/build/.uv -t mcp-optimizer .

Check image size

docker images mcp-optimizer

Run container

docker run -p 8000:8000 mcp-optimizer:latest

For development with volume mounting

docker run -p 8000:8000 -v $(pwd):/app mcp-optimizer:latest

Test container functionality

docker run --rm mcp-optimizer:latest python -c "from mcp_optimizer.mcp_server import create_mcp_server; print('✅ MCP Optimizer works!')"

code

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Git Flow Policy
This project follows a standard Git Flow workflow:
- **Feature branches** → `develop` branch
- **Release branches** → `main` branch  
- **Hotfix branches** → `main` and `develop` branches

📚 **Documentation**:
- [Contributing Guide](CONTRIBUTING.md) - Complete development workflow and Git Flow policy
- [Release Process](.github/RELEASE_PROCESS.md) - How releases are created and automated
- [Repository Setup](.github/REPOSITORY_SETUP.md) - Complete setup guide including branch protection and security configuration

### Development Setup

Clone and setup

git clone https://github.com/dmitryanchikov/mcp-optimizer.git

cd mcp-optimizer

Create feature branch from develop

git checkout develop

git checkout -b feature/your-feature-name

Install dependencies

uv sync --extra dev

Run tests

uv run pytest tests/ -v

Run linting

uv run ruff check src/

uv run mypy src/

Create PR to develop branch (not main!)

code

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [OR-Tools](https://developers.google.com/optimization) - Google's optimization tools
- [PuLP](https://coin-or.github.io/pulp/) - Linear programming in Python
- [FastMCP](https://github.com/jlowin/fastmcp) - Fast MCP server implementation

## 📞 Support

- 📧 Email: support@mcp-optimizer.com
- 🐛 Issues: [GitHub Issues](https://github.com/dmitryanchikov/mcp-optimizer/issues)
- 📖 Documentation: [docs/](docs/)

---

**Made with ❤️ for the optimization community**

## 📊 Docker Image Size Analysis

The MCP Optimizer Docker image has been optimized to balance functionality and size:

| Component | Size | % of Total | Description |
|-----------|------|------------|-------------|
| **Python packages (/venv)** | **237.0 MB** | **42.8%** | Virtual environment with dependencies |
| **System libraries (/usr)** | **173.2 MB** | **31.3%** | Base Debian system + Python |
| **Other** | **137.4 MB** | **24.8%** | Base image, filesystem |
| **Configuration (/var, /etc)** | **6.2 MB** | **1.1%** | System settings |
| **Application code (/code)** | **0.2 MB** | **0.04%** | MCP Optimizer source code |

### Key Dependencies by Size
- **OR-Tools**: 75.0 MB (27.8% of venv) - Critical optimization solver (requires pandas + numpy)
- **pandas**: 45.0 MB (16.7% of venv) - Required by OR-Tools for data operations
- **NumPy**: 24.0 MB (8.9% of venv) - Required by OR-Tools for numerical computing
- **PuLP**: 34.9 MB (12.9% of venv) - Linear programming solver  
- **FastMCP**: 15.2 MB (5.6% of venv) - MCP server framework
- **Pydantic**: 12.8 MB (4.7% of venv) - Data validation

### Dependencies Analysis
- **Core packages cannot be reduced further**: OR-Tools (our main optimization engine) requires both pandas and numpy as mandatory dependencies
- **Optional examples moved**: Additional packages for examples (streamlit, plotly) moved to `[examples]` extra
- **Minimal core impact**: Moving examples to optional dependencies only affects development/demo usage

### Image Optimization
- **Current optimized size**: ~420MB
- **Core functionality**: Includes all necessary dependencies for production optimization
- **Example support**: Install with `[examples]` extra for additional demo functionality
- **OR-Tools constraint**: Cannot remove pandas/numpy due to hard dependency requirements

Mcp Optimizer

Documentation

MCP Optimizer

🚀 Quick Start

Recommended Installation Methods (by Priority)

1. 🐳 Docker (Recommended) - Cross-platform

2. 📦 pip + venv - Cross-platform

3. 🚀 uvx - Linux/Windows (full), macOS (partially)

🍎 macOS Specifics

Transport Mode Recommendations

Integration with LLM Clients

Claude Desktop Integration

Cursor Integration

Other LLM Clients

Advanced Installation Options

Local Development

Local Package Build and Run

Docker with Custom Configuration

Standalone Server Commands

Transport Modes

🔧 Platform Compatibility & Troubleshooting

macOS Compatibility

Linux/Windows Compatibility

Solver Availability by Platform

🔧 macOS uvx Troubleshooting

Problem: OR-Tools Library Issues with uvx

📊 Functionality Impact by Installation Method

🛠️ Solutions (in order of preference)

1. Automated Fix Script (Recommended)

2. Manual Fix

3. Use pip (Always Works)

4. Use Docker (Production Ready)

🎯 Features

Supported Optimization Problem Types:

Testing

Automated Test Scripts

📊 Usage Examples

Linear Programming

Run debug tools to check server structure

This will show:

- Available MCP tools

- Tool types and attributes

- Server configuration

Run comprehensive tests

This tests:

- All optimization tools (9 categories)

- Server health and functionality

- Performance benchmarks

- End-to-end workflows

Standard build

Build with development dependencies

Build with cache mount for faster rebuilds

Check image size

Run container

For development with volume mounting

Test container functionality

Clone and setup

Create feature branch from develop

Install dependencies

Run tests

Run linting

Create PR to develop branch (not main!)

Similar MCP

Davinci Resolve Mcp

Biothings Mcp

Fhir Mcp Server

Omop Mcp

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Davinci Resolve Mcp

Biothings Mcp

Fhir Mcp Server

Omop Mcp

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare