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

# 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

# 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)

# 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:

# 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:

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

3. Add to your claude_desktop_config.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

# 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:

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

Option 3: Using uvx Add to your claude_desktop_config.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)

# 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 <container-name>

# 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):

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

Alternative configurations:

// 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

# 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:

# 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

# 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

# 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)

# 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)

# 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

# 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:

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

2. uvx shows OR-Tools warnings:

   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:

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)

# 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

# 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)

# Install dependencies first
brew install or-tools

# Install package
pip install mcp-optimizer
mcp-optimizer

4. Use Docker (Production Ready)

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:

# 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:

# 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:

# 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

from mcp_optimizer.tools.linear_programming import solve_linear_program

# Maximize 3x + 2y subject to:
# x + y <= 4
# 2x + y <= 6
# 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": "<=", "rhs": 4},
    {"expression": {"x": 2, "y": 1}, "operator": "<=", "rhs": 6}
]

result = solve_linear_program(objective, variables, constraints)
# Result: x=2.0, y=2.0, objective=10.0

Assignment Problem

from mcp_optimizer.tools.assignment import solve_assignment_problem

workers = ["Alice", "Bob", "Charlie"]
tasks = ["Task1", "Task2", "Task3"]
costs = [
    [4, 1, 3],  # Alice's costs for each task
    [2, 0, 5],  # Bob's costs for each task
    [3, 2, 2]   # Charlie's costs for each task
]

result = solve_assignment_problem(workers, tasks, costs)
# Result: Total cost = 5.0 with optimal assignments

Knapsack Problem

from mcp_optimizer.tools.knapsack import solve_knapsack_problem

items = [
    {"name": "Item1", "weight": 10, "value": 60},
    {"name": "Item2", "weight": 20, "value": 100},
    {"name": "Item3", "weight": 30, "value": 120}
]

result = solve_knapsack_problem(items, capacity=50)
# Result: Total value = 220.0 with optimal item selection

Portfolio Optimization

from mcp_optimizer.tools.financial import optimize_portfolio

assets = [
    {"name": "Stock A", "expected_return": 0.12, "risk": 0.18},
    {"name": "Stock B", "expected_return": 0.10, "risk": 0.15},
    {"name": "Bond C", "expected_return": 0.06, "risk": 0.08}
]

result = optimize_portfolio(
    assets=assets,
    objective="minimize_risk",
    budget=10000,
    risk_tolerance=0.15
)
# Result: Optimal portfolio allocation with minimized risk

🏗️ Architecture

mcp-optimizer/
├── LICENSE                     # MIT License
├── README.md                   # Project documentation
├── CHANGELOG.md               # Release notes
├── CONTRIBUTING.md            # Contribution guidelines
├── pyproject.toml             # Python project configuration
├── uv.lock                    # Dependency lock file
├── main.py                    # Entry point
├── Dockerfile                 # Main Docker configuration
├── docker-compose.yml         # Multi-service setup
├── .dockerignore             # Docker ignore rules
├── .gitignore                # Git ignore rules
├── .python-version           # Python version specification
├── src/mcp_optimizer/        # Main source code
│   ├── __init__.py
│   ├── __main__.py           # Module entry point
│   ├── main.py               # Application entry point
│   ├── mcp_server.py         # MCP server implementation
│   ├── config.py             # Configuration management
│   ├── tools/                # 9 categories of optimization tools
│   │   ├── linear_programming.py
│   │   ├── assignment.py
│   │   ├── knapsack.py
│   │   ├── routing.py
│   │   ├── scheduling.py
│   │   ├── financial.py
│   │   └── production.py
│   ├── solvers/              # PuLP and OR-Tools integration
│   │   ├── pulp_solver.py
│   │   └── ortools_solver.py
│   ├── schemas/              # Pydantic validation schemas
│   └── utils/                # Utility functions
├── tests/                    # Comprehensive test suite
│   ├── test_tools/           # Tool-specific tests
│   ├── test_solvers/         # Solver tests
│   └── test_integration/     # Integration tests
├── scripts/                  # Automation scripts
├── examples/                 # Usage examples and prompts
│   ├── en/                   # English examples
│   └── ru/                   # Russian examples
├── k8s/                      # Kubernetes deployment manifests
└── monitoring/               # Grafana/Prometheus setup
    └── grafana/
        └── datasources/

🧪 Test Results

✅ Comprehensive Test Suite

🧪 Starting Comprehensive MCP Optimizer Tests
==================================================
✅ Server Health PASSED
✅ Linear Programming PASSED
✅ Assignment Problems PASSED  
✅ Knapsack Problems PASSED
✅ Routing Problems PASSED
✅ Scheduling Problems PASSED
✅ Financial Optimization PASSED
✅ Production Planning PASSED
✅ Performance Test PASSED

📊 Test Results: 9 passed, 0 failed
🎉 All tests passed! MCP Optimizer is ready for production!

✅ Unit Tests

• 66 tests passed, 9 skipped
• Execution time: 0.45 seconds
• All core components functional

📈 Performance Metrics

• Linear Programming: ~0.01s
• Assignment Problems: ~0.01s
• Knapsack Problems: ~0.01s
• Complex test suite: 0.02s for 3 optimization problems
• Overall performance: 🚀 Excellent!

🔧 Technical Details

Core Solvers

• OR-Tools: For assignment, transportation, knapsack problems
• PuLP: For linear/integer programming
• FastMCP: For MCP server integration

Supported Solvers

• CBC, GLPK, GUROBI, CPLEX (via PuLP)
• SCIP, CP-SAT (via OR-Tools)

Key Features

• ✅ Full MCP protocol integration
• ✅ Comprehensive input validation
• ✅ Robust error handling
• ✅ High-performance optimization
• ✅ Production-ready architecture
• ✅ Extensive test coverage
• ✅ Docker and Kubernetes support

📋 Requirements

• Python 3.11+
• uv (for dependency management)
• OR-Tools (automatically installed)
• PuLP (automatically installed)

🚀 Production Deployment

Docker

# Build image
docker build -t mcp-optimizer .

# Run container
docker run -p 8000:8000 mcp-optimizer

Kubernetes

# Deploy to Kubernetes
kubectl apply -f k8s/

Monitoring

# Start monitoring stack
docker-compose up -d

🎯 Project Status

✅ PRODUCTION READY 🚀

• All core optimization tools implemented and tested
• MCP server fully functional
• Comprehensive test coverage (66 unit tests + 9 integration tests)
• OR-Tools integration confirmed working
• Performance optimized (< 30s for complex test suites)
• Ready for production deployment

📖 Usage Examples

The examples/ directory contains practical examples and prompts for using MCP Optimizer with Large Language Models (LLMs):

Available Examples

• 📊 Linear Programming (RU | EN)
  • Production optimization, diet planning, transportation, blending problems
• 👥 Assignment Problems (RU | EN)
  • Employee-project assignment, machine-order allocation, task distribution
• 💰 Portfolio Optimization (RU | EN)
  • Investment portfolios, retirement planning, risk management

How to Use Examples

1. For LLM Integration: Copy the prompt text and provide it to your LLM with MCP Optimizer access
2. For Direct API Usage: Use the provided API structures directly with MCP Optimizer functions
3. For Learning: Understand different optimization problem types and formulations

Each example includes:

• Problem descriptions and real-world scenarios
• Ready-to-use prompts for LLMs
• Technical API structures
• Common activation phrases
• Practical applications

🔄 Recent Updates

Latest Release Features:

1. Function Exports - Added exportable functions to all tool modules:

   • solve_linear_program() in linear_programming.py
   • solve_assignment_problem() in assignment.py
   • solve_knapsack_problem() in knapsack.py
   • optimize_portfolio() in financial.py
   • optimize_production() in production.py

2. Enhanced Testing - Updated comprehensive test suite with correct function signatures

3. OR-Tools Integration - Confirmed full functionality of all OR-Tools components

🚀 Fully Automated Release Process

New Simplified Git Flow (3 steps!)

The project uses a fully automated release process:

1. Create Release Branch

# For minor release (auto-increment)
uv run python scripts/release.py --type minor

# For specific version
uv run python scripts/release.py 0.2.0

# For hotfix
uv run python scripts/release.py --hotfix --type patch

# Preview changes
uv run python scripts/release.py --type minor --dry-run

2. Create PR to main

# Create PR: release/v0.3.0 → main
gh pr create --base main --head release/v0.3.0 --title "Release v0.3.0"

3. Merge PR - DONE! 🎉

After PR merge, automatically happens:

• ✅ Create tag v0.3.0
• ✅ Publish to PyPI
• ✅ Publish Docker images
• ✅ Create GitHub Release
• ✅ Merge main back to develop
• ✅ Cleanup release branch

NO NEED to run manual_finalize_release.py manually anymore!

🔒 Secure Detection: Uses hybrid approach combining GitHub branch protection with automated release detection. See Release Process 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

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

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!')"

🤝 Contributing

We welcome contributions! Please see 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 - Complete development workflow and Git Flow policy
• Release Process - How releases are created and automated
• Repository Setup - 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!)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OR-Tools - Google's optimization tools
• PuLP - Linear programming in Python
• FastMCP - Fast MCP server implementation

📞 Support

• 📧 Email: support@mcp-optimizer.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: 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