{"id":28344075,"url":"https://github.com/dmitryanchikov/mcp-optimizer","last_synced_at":"2026-08-28T03:15:30.035Z","repository":{"id":295570962,"uuid":"990076704","full_name":"dmitryanchikov/mcp-optimizer","owner":"dmitryanchikov","description":"Mathematical Optimization MCP Server with PuLP and OR-Tools support","archived":false,"fork":false,"pushed_at":"2025-11-05T20:52:20.000Z","size":534,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T15:11:43.441Z","etag":null,"topics":["mcp-server","optimization-tools"],"latest_commit_sha":null,"homepage":"https://mcp-optimizer.dmitryanch.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmitryanchikov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-25T13:05:00.000Z","updated_at":"2025-11-24T16:15:17.000Z","dependencies_parsed_at":"2025-05-26T09:36:25.458Z","dependency_job_id":"3cff3379-6553-4ef4-b237-ec1dc06ce499","html_url":"https://github.com/dmitryanchikov/mcp-optimizer","commit_stats":null,"previous_names":["dmitryanchikov/mcp-optimizer"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/dmitryanchikov/mcp-optimizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitryanchikov%2Fmcp-optimizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitryanchikov%2Fmcp-optimizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitryanchikov%2Fmcp-optimizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitryanchikov%2Fmcp-optimizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmitryanchikov","download_url":"https://codeload.github.com/dmitryanchikov/mcp-optimizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitryanchikov%2Fmcp-optimizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36948614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-28T02:00:06.244Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp-server","optimization-tools"],"created_at":"2025-05-27T07:59:47.795Z","updated_at":"2026-08-28T03:15:30.029Z","avatar_url":"https://github.com/dmitryanchikov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Optimizer\n\n🚀 **Mathematical Optimization MCP Server** with PuLP and OR-Tools support\n\n[![Tests](https://img.shields.io/badge/tests-66%20passed-brightgreen)](https://github.com/dmitryanchikov/mcp-optimizer)\n[![Coverage](https://img.shields.io/badge/coverage-48%25-yellow)](https://github.com/dmitryanchikov/mcp-optimizer)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n📖 **Quick Links:** [🚀 Quick Start](#-quick-start) | [🔧 macOS Troubleshooting](#-macos-uvx-troubleshooting) | [📊 Examples](#-usage-examples) | [🎯 Features](#-features)\n\n## 🚀 Quick Start\n\n### Recommended Installation Methods (by Priority)\n\n### 1. 🐳 Docker (Recommended) - Cross-platform\n**Most stable method with full functionality**\n\n```bash\n# Run with STDIO transport (for MCP clients)\ndocker run --rm -i ghcr.io/dmitryanchikov/mcp-optimizer:latest\n\n# Run with SSE transport (for remote clients)\ndocker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \\\n  ghcr.io/dmitryanchikov/mcp-optimizer:latest\n\n# Check SSE endpoint\ncurl -i http://localhost:8000/sse\n```\n\n### 2. 📦 pip + venv - Cross-platform  \n**Standard approach**\n\n```bash\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n# or .venv\\Scripts\\activate  # Windows\n\n# Install mcp-optimizer\npip install mcp-optimizer\n\n# For SSE issues, use stable dependency versions:\n# pip install \"mcp-optimizer[stable]\"\n\n# Run (STDIO mode recommended)\nmcp-optimizer --transport stdio\n```\n\n### 3. 🚀 uvx - Linux/Windows (full), macOS (partially)\n\n```bash\n# Linux/Windows - works out of the box\nuvx mcp-optimizer\n\n# macOS - requires Python 3.12\nuvx --python python3.12 mcp-optimizer\n\n# STDIO mode recommended\nuvx mcp-optimizer --transport stdio\n```\n\n**macOS users:** If you encounter OR-Tools related errors, see [🔧 macOS uvx Troubleshooting](#-macos-uvx-troubleshooting) section for automated fix scripts.\n\n### 🍎 macOS Specifics\n\n**OR-Tools support:**\n- **uvx**: PuLP only (limited functionality)\n- **pip**: full OR-Tools support  \n- **Docker**: full OR-Tools support\n\n**For full OR-Tools support via pip:**\n```bash\n# Install OR-Tools via Homebrew\nbrew install or-tools\n\n# Then install mcp-optimizer\npip install \"mcp-optimizer[stable]\"\n```\n\n### Transport Mode Recommendations\n\n| Installation Method | Recommended Transport | Why |\n|---------------------|----------------------|-----|\n| Docker | SSE | Full stability |\n| pip + venv | STDIO | Avoids dependency issues with newer versions |\n| uvx | STDIO | Maximum compatibility |\n\n### Integration with LLM Clients\n\n#### Claude Desktop Integration\n\n**Option 1: Using Docker (Recommended)**\n1. Install Claude Desktop from [claude.ai](https://claude.ai/download)\n2. Pull the Docker image:\n```bash\ndocker pull ghcr.io/dmitryanchikov/mcp-optimizer:latest\n```\n3. Add to your `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"ghcr.io/dmitryanchikov/mcp-optimizer:latest\",\n        \"python\", \"main.py\"\n      ]\n    }\n  }\n}\n```\n4. Restart Claude Desktop and look for the 🔨 tools icon\n\n**Option 2: Using pip + venv**\n```bash\n# Create virtual environment and install\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\npip install mcp-optimizer\n```\nThen add to your Claude Desktop config:\n```json\n{\n  \"mcpServers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"mcp-optimizer\"\n    }\n  }\n}\n```\n\n**Option 3: Using uvx**\nAdd to your `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-optimizer\"]\n    }\n  }\n}\n```\n*Note: On macOS, uvx provides limited functionality (PuLP solver only) or see [🔧 macOS uvx Troubleshooting](#-macos-uvx-troubleshooting)*\n\n**Advanced Docker Setup (for remote MCP clients)**\n```bash\n# Run SSE server on port 8000 (uses environment variable)\ndocker run -d -p 8000:8000 -e TRANSPORT_MODE=sse \\\n  ghcr.io/dmitryanchikov/mcp-optimizer:latest\n\n# Or with CLI argument and custom port\ndocker run -d -p 9000:9000 ghcr.io/dmitryanchikov/mcp-optimizer:latest \\\n  python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000\n\n# Check server status\ndocker logs \u003ccontainer-name\u003e\n\n# Verify SSE endpoint (should show event stream)\ncurl -i http://localhost:8000/sse\n```\n**SSE Endpoint**: `http://localhost:8000/sse` (Server-Sent Events for MCP communication)\n\n#### Cursor Integration\n\n1. Install the MCP extension in Cursor\n2. Add mcp-optimizer to your workspace settings (Docker recommended):\n```json\n{\n  \"mcp.servers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"ghcr.io/dmitryanchikov/mcp-optimizer:latest\",\n        \"python\", \"main.py\"\n      ]\n    }\n  }\n}\n```\n\n**Alternative configurations:**\n```json\n// Using pip installation\n{\n  \"mcp.servers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"mcp-optimizer\"\n    }\n  }\n}\n\n// Using uvx (limited functionality on macOS)\n{\n  \"mcp.servers\": {\n    \"mcp-optimizer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-optimizer\"]\n    }\n  }\n}\n```\n\n#### Other LLM Clients\n\nFor other MCP-compatible clients (Continue, Cody, etc.), use similar configuration patterns. **Recommended priority:**\n\n1. **Docker** (maximum stability across platforms)\n2. **pip + venv** (standard Python approach)  \n3. **uvx** (quick testing, limited on macOS)\n\n### Advanced Installation Options\n\n#### Local Development\n```bash\n# Clone the repository\ngit clone https://github.com/dmitryanchikov/mcp-optimizer.git\ncd mcp-optimizer\n\n# Install dependencies with uv\nuv sync --extra dev\n\n# Run the server\nuv run python main.py\n```\n\n#### Local Package Build and Run\n\nFor testing and development, you can build the package locally and run it with uvx:\n\n```bash\n# Build the package locally\nuv build\n\n# Run with uvx from local wheel file\nuvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer\n\n# Or run with help to see available options\nuvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer --help\n\n# Test the local package with a simple MCP message\necho '{\"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\n```\n\n**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.\n\n#### Docker with Custom Configuration\n```bash\n# Build locally with optimization\ngit clone https://github.com/dmitryanchikov/mcp-optimizer.git\ncd mcp-optimizer\ndocker build -t mcp-optimizer:optimized .\ndocker run -p 8000:8000 mcp-optimizer:optimized\n\n# Check optimized image size (398MB vs 1.03GB original - 61% reduction!)\ndocker images mcp-optimizer:optimized\n\n# Test the optimized image\n./scripts/test_docker_optimization.sh\n```\n\n#### Standalone Server Commands\n```bash\n# Run directly with uvx (no installation needed)\nuvx mcp-optimizer\n\n# Or run specific commands\nuvx mcp-optimizer --help\n\n# With pip installation\nmcp-optimizer\n\n# Or run with Python module (use main.py for stdio mode)\npython main.py\n```\n\n#### Transport Modes\n\nMCP Optimizer supports two MCP transport protocols:\n- **STDIO**: Standard input/output for direct MCP client integration (Claude Desktop, Cursor, etc.)\n- **SSE**: Server-Sent Events over HTTP for web-based MCP clients and remote integrations\n\n**STDIO Transport (Default - for MCP clients like Claude Desktop)**\n```bash\n# Default STDIO mode for MCP protocol\nuvx mcp-optimizer\n# or\nuvx mcp-optimizer --transport stdio\n# or\nuv run python -m mcp_optimizer.main --transport stdio\n# or\npython main.py\n```\n\n**SSE Transport (for remote MCP clients)**\n```bash\n# SSE mode for remote MCP clients (default port 8000)\nuvx mcp-optimizer --transport sse\n# or\nuv run python -m mcp_optimizer.main --transport sse\n\n# Custom host and port\nuvx mcp-optimizer --transport sse --host 0.0.0.0 --port 9000\n# or\nuv run python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000\n\n# With debug mode\nuvx mcp-optimizer --transport sse --debug --log-level DEBUG\n```\n\n**Available CLI Options**\n```bash\n# Show all available options\nuvx mcp-optimizer --help\n\n# Options:\n#   --transport {stdio,sse}    MCP transport protocol (default: stdio)\n#   --port PORT               Port for SSE transport (default: 8000)\n#   --host HOST               Host for SSE transport (default: 127.0.0.1)\n#   --debug                   Enable debug mode\n#   --reload                  Enable auto-reload for development\n#   --log-level {DEBUG,INFO,WARNING,ERROR}  Logging level (default: INFO)\n#\n# Environment Variables:\n#   TRANSPORT_MODE={stdio,sse}  Override transport mode\n#   SERVER_HOST=0.0.0.0        Override server host\n#   SERVER_PORT=8000           Override server port\n```\n\n## 🔧 Platform Compatibility \u0026 Troubleshooting\n\n### macOS Compatibility\n\n**✅ Full Functionality:**\n- **Homebrew + pip**: `brew install or-tools \u0026\u0026 pip install mcp-optimizer`\n- **Virtual environments**: `python -m venv venv \u0026\u0026 source venv/bin/activate \u0026\u0026 pip install ortools mcp-optimizer`\n- **Docker**: Full OR-Tools support in containers\n\n**⚠️ Limited Functionality:**\n- **uvx (isolated environments)**: Only PuLP solver available due to OR-Tools native library paths\n- **Fallback behavior**: Automatically switches to PuLP when OR-Tools unavailable\n\n**Common Issues \u0026 Solutions:**\n\n1. **OR-Tools \"Library not loaded\" error:**\n   ```bash\n   # Solution: Install via Homebrew\n   brew install or-tools\n   # Then use regular pip/venv instead of uvx\n   ```\n\n2. **uvx shows OR-Tools warnings:**\n   ```bash\n   WARNING: OR-Tools not available: No module named 'ortools'\n   ```\n   This is expected - uvx provides fallback functionality with PuLP solver.\n\n3. **Best practices for macOS:**\n   - Use Docker for production deployments\n   - Use Homebrew + pip for development\n   - Use uvx for quick testing (limited functionality)\n\n### Linux/Windows Compatibility\n\n**✅ Full Functionality:**\n- **uvx**: Works out of the box with OR-Tools\n- **pip**: Standard installation\n- **Docker**: Recommended for production\n\n### Solver Availability by Platform\n\n  | Platform | uvx | pip | Docker |\n  |----------|-----|-----|--------|\n  | **macOS** | PuLP only | ✅ Full | ✅ Full |\n  | **Linux** | ✅ Full | ✅ Full | ✅ Full |\n  | **Windows** | ✅ Full | ✅ Full | ✅ Full |\n\n**Solver Features:**\n- **OR-Tools**: Advanced algorithms (CP-SAT, routing, scheduling)\n- **PuLP**: Basic linear programming, reliable fallback\n\n## 🔧 macOS uvx Troubleshooting \n\n### Problem: OR-Tools Library Issues with uvx\n\n**Common Error Messages:**\n```\nLibrary not loaded: /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib\nImportError: No module named 'ortools'\nWARNING: OR-Tools not available\n```\n\n**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.\n\n### 📊 Functionality Impact by Installation Method\n\n**✅ Available with uvx + fallback (PuLP solver only)**:\n- **Linear Programming** - Basic optimization, simplex method\n- **Financial Optimization** - Portfolio optimization, risk management  \n- **Production Planning** - Resource allocation, inventory management\n\n**❌ Lost with uvx (requires OR-Tools)**:\n- **Assignment Problems** - Hungarian algorithm, transportation problems\n- **Integer Programming** - Mixed-integer, binary programming (SCIP/CBC)\n- **Knapsack Problems** - Discrete optimization, multiple variants\n- **Vehicle Routing** - TSP, CVRP, time windows (constraint programming)\n- **Job Scheduling** - CP-SAT solver, resource planning\n\n### 🛠️ Solutions (in order of preference)\n\n#### 1. Automated Fix Script (Recommended)\n```bash\n# Smart adaptive script - no hardcoded versions!\n# Automatically detects your system libraries and Python versions\n./scripts/fix_macos_uvx.sh\n\n# Then uvx works with full functionality\nuvx mcp-optimizer --transport stdio\n```\n\n#### 2. Manual Fix\n```bash\n# Install system dependencies\nbrew install or-tools scip\n\n# Create symlink for hardcoded path\nsudo mkdir -p /Users/corentinl/work/stable/temp_python3.13/lib/\nsudo ln -sf /opt/homebrew/lib/libscip.9.2.dylib /Users/corentinl/work/stable/temp_python3.13/lib/libscip.9.2.dylib\n\n# Test fix\nuvx mcp-optimizer --help\n```\n\n#### 3. Use pip (Always Works)\n```bash\n# Install dependencies first\nbrew install or-tools\n\n# Install package\npip install mcp-optimizer\nmcp-optimizer\n```\n\n#### 4. Use Docker (Production Ready)\n```bash\ndocker run -p 8000:8000 mcp-optimizer\n```\n\n## 🎯 Features\n\n### Supported Optimization Problem Types:\n- **Linear Programming** - Maximize/minimize linear objective functions\n- **Assignment Problems** - Optimal resource allocation using Hungarian algorithm\n- **Transportation Problems** - Logistics and supply chain optimization\n- **Knapsack Problems** - Optimal item selection (0-1, bounded, unbounded)\n- **Routing Problems** - TSP and VRP with time windows\n- **Scheduling Problems** - Job and shift scheduling\n- **Integer Programming** - Discrete optimization problems\n- **Financial Optimization** - Portfolio optimization and risk management\n- **Production Planning** - Multi-period production planning\n\n### Testing\n\n#### Automated Test Scripts\n\n**Quick Testing:**\n```bash\n# Test local package build and functionality\n./scripts/test_local_package.sh\n\n# Test Docker container build and functionality  \n./scripts/test_docker_container.sh\n\n# Run comprehensive test suite (both package and Docker)\n./scripts/test_all.sh\n\n# Run only specific tests\n./scripts/test_all.sh --skip-docker    # Skip Docker tests\n./scripts/test_all.sh --skip-package   # Skip package tests\n```\n\n**Manual Testing:**\n```bash\n# Run simple functionality tests\nuv run python tests/test_integration/comprehensive_test.py\n\n# Run comprehensive integration tests\nuv run python tests/test_integration/comprehensive_test.py\n\n# Run all unit tests\nuv run pytest tests/ -v\n\n# Run with coverage\nuv run pytest tests/ --cov=src/mcp_optimizer --cov-report=html\n```\n\n**Test Scripts Features:**\n- ✅ **Local Package Testing**: Build, STDIO/SSE modes, CLI functionality\n- ✅ **Docker Container Testing**: Image build, environment variables, health checks\n- ✅ **Comprehensive Suite**: Parallel execution with detailed reporting\n- ✅ **Automatic Cleanup**: Processes and containers cleaned up after tests\n- ✅ **Cross-Platform**: Works on macOS, Linux (requires Docker for container tests)\n\n**Requirements:**\n- For local tests: `uv`, `curl`, `lsof`, `gtimeout`/`timeout`\n- For Docker tests: `docker` + local requirements\n- macOS: `brew install coreutils` (for gtimeout)\n\n**CI/CD Integration:**\n```yaml\n# GitHub Actions example\n- name: Test Package\n  run: ./scripts/test_local_package.sh\n- name: Test Docker\n  run: ./scripts/test_docker_container.sh\n```\n\n## 📊 Usage Examples\n\n### Linear Programming\n```python\nfrom mcp_optimizer.tools.linear_programming import solve_linear_program\n\n# Maximize 3x + 2y subject to:\n# x + y \u003c= 4\n# 2x + y \u003c= 6\n# x, y \u003e= 0\n\nobjective = {\"sense\": \"maximize\", \"coefficients\": {\"x\": 3, \"y\": 2}}\nvariables = {\n    \"x\": {\"type\": \"continuous\", \"lower\": 0},\n    \"y\": {\"type\": \"continuous\", \"lower\": 0}\n}\nconstraints = [\n    {\"expression\": {\"x\": 1, \"y\": 1}, \"operator\": \"\u003c=\", \"rhs\": 4},\n    {\"expression\": {\"x\": 2, \"y\": 1}, \"operator\": \"\u003c=\", \"rhs\": 6}\n]\n\nresult = solve_linear_program(objective, variables, constraints)\n# Result: x=2.0, y=2.0, objective=10.0\n```\n\n### Assignment Problem\n```python\nfrom mcp_optimizer.tools.assignment import solve_assignment_problem\n\nworkers = [\"Alice\", \"Bob\", \"Charlie\"]\ntasks = [\"Task1\", \"Task2\", \"Task3\"]\ncosts = [\n    [4, 1, 3],  # Alice's costs for each task\n    [2, 0, 5],  # Bob's costs for each task\n    [3, 2, 2]   # Charlie's costs for each task\n]\n\nresult = solve_assignment_problem(workers, tasks, costs)\n# Result: Total cost = 5.0 with optimal assignments\n```\n\n### Knapsack Problem\n```python\nfrom mcp_optimizer.tools.knapsack import solve_knapsack_problem\n\nitems = [\n    {\"name\": \"Item1\", \"weight\": 10, \"value\": 60},\n    {\"name\": \"Item2\", \"weight\": 20, \"value\": 100},\n    {\"name\": \"Item3\", \"weight\": 30, \"value\": 120}\n]\n\nresult = solve_knapsack_problem(items, capacity=50)\n# Result: Total value = 220.0 with optimal item selection\n```\n\n### Portfolio Optimization\n```python\nfrom mcp_optimizer.tools.financial import optimize_portfolio\n\nassets = [\n    {\"name\": \"Stock A\", \"expected_return\": 0.12, \"risk\": 0.18},\n    {\"name\": \"Stock B\", \"expected_return\": 0.10, \"risk\": 0.15},\n    {\"name\": \"Bond C\", \"expected_return\": 0.06, \"risk\": 0.08}\n]\n\nresult = optimize_portfolio(\n    assets=assets,\n    objective=\"minimize_risk\",\n    budget=10000,\n    risk_tolerance=0.15\n)\n# Result: Optimal portfolio allocation with minimized risk\n```\n\n## 🏗️ Architecture\n\n```\nmcp-optimizer/\n├── LICENSE                     # MIT License\n├── README.md                   # Project documentation\n├── CHANGELOG.md               # Release notes\n├── CONTRIBUTING.md            # Contribution guidelines\n├── pyproject.toml             # Python project configuration\n├── uv.lock                    # Dependency lock file\n├── main.py                    # Entry point\n├── Dockerfile                 # Main Docker configuration\n├── docker-compose.yml         # Multi-service setup\n├── .dockerignore             # Docker ignore rules\n├── .gitignore                # Git ignore rules\n├── .python-version           # Python version specification\n├── src/mcp_optimizer/        # Main source code\n│   ├── __init__.py\n│   ├── __main__.py           # Module entry point\n│   ├── main.py               # Application entry point\n│   ├── mcp_server.py         # MCP server implementation\n│   ├── config.py             # Configuration management\n│   ├── tools/                # 9 categories of optimization tools\n│   │   ├── linear_programming.py\n│   │   ├── assignment.py\n│   │   ├── knapsack.py\n│   │   ├── routing.py\n│   │   ├── scheduling.py\n│   │   ├── financial.py\n│   │   └── production.py\n│   ├── solvers/              # PuLP and OR-Tools integration\n│   │   ├── pulp_solver.py\n│   │   └── ortools_solver.py\n│   ├── schemas/              # Pydantic validation schemas\n│   └── utils/                # Utility functions\n├── tests/                    # Comprehensive test suite\n│   ├── test_tools/           # Tool-specific tests\n│   ├── test_solvers/         # Solver tests\n│   └── test_integration/     # Integration tests\n├── scripts/                  # Automation scripts\n├── examples/                 # Usage examples and prompts\n│   ├── en/                   # English examples\n│   └── ru/                   # Russian examples\n├── k8s/                      # Kubernetes deployment manifests\n└── monitoring/               # Grafana/Prometheus setup\n    └── grafana/\n        └── datasources/\n```\n\n## 🧪 Test Results\n\n### ✅ Comprehensive Test Suite\n```\n🧪 Starting Comprehensive MCP Optimizer Tests\n==================================================\n✅ Server Health PASSED\n✅ Linear Programming PASSED\n✅ Assignment Problems PASSED  \n✅ Knapsack Problems PASSED\n✅ Routing Problems PASSED\n✅ Scheduling Problems PASSED\n✅ Financial Optimization PASSED\n✅ Production Planning PASSED\n✅ Performance Test PASSED\n\n📊 Test Results: 9 passed, 0 failed\n🎉 All tests passed! MCP Optimizer is ready for production!\n```\n\n### ✅ Unit Tests\n- **66 tests passed, 9 skipped**\n- **Execution time: 0.45 seconds**\n- **All core components functional**\n\n### 📈 Performance Metrics\n- **Linear Programming**: ~0.01s\n- **Assignment Problems**: ~0.01s  \n- **Knapsack Problems**: ~0.01s\n- **Complex test suite**: 0.02s for 3 optimization problems\n- **Overall performance**: 🚀 Excellent!\n\n## 🔧 Technical Details\n\n### Core Solvers\n- **OR-Tools**: For assignment, transportation, knapsack problems\n- **PuLP**: For linear/integer programming\n- **FastMCP**: For MCP server integration\n\n### Supported Solvers\n- **CBC, GLPK, GUROBI, CPLEX** (via PuLP)\n- **SCIP, CP-SAT** (via OR-Tools)\n\n### Key Features\n- ✅ Full MCP protocol integration\n- ✅ Comprehensive input validation\n- ✅ Robust error handling\n- ✅ High-performance optimization\n- ✅ Production-ready architecture\n- ✅ Extensive test coverage\n- ✅ Docker and Kubernetes support\n\n## 📋 Requirements\n\n- **Python 3.11+**\n- **uv** (for dependency management)\n- **OR-Tools** (automatically installed)\n- **PuLP** (automatically installed)\n\n## 🚀 Production Deployment\n\n### Docker\n```bash\n# Build image\ndocker build -t mcp-optimizer .\n\n# Run container\ndocker run -p 8000:8000 mcp-optimizer\n```\n\n### Kubernetes\n```bash\n# Deploy to Kubernetes\nkubectl apply -f k8s/\n```\n\n### Monitoring\n```bash\n# Start monitoring stack\ndocker-compose up -d\n```\n\n## 🎯 Project Status\n\n**✅ PRODUCTION READY** 🚀\n\n- All core optimization tools implemented and tested\n- MCP server fully functional\n- Comprehensive test coverage (66 unit tests + 9 integration tests)\n- OR-Tools integration confirmed working\n- Performance optimized (\u003c 30s for complex test suites)\n- Ready for production deployment\n\n## 📖 Usage Examples\n\nThe `examples/` directory contains practical examples and prompts for using MCP Optimizer with Large Language Models (LLMs):\n\n### Available Examples\n- **📊 Linear Programming** ([RU](examples/ru/linear_programming.md) | [EN](examples/en/linear_programming.md))\n  - Production optimization, diet planning, transportation, blending problems\n- **👥 Assignment Problems** ([RU](examples/ru/assignment_problems.md) | [EN](examples/en/assignment_problems.md))\n  - Employee-project assignment, machine-order allocation, task distribution\n- **💰 Portfolio Optimization** ([RU](examples/ru/portfolio_optimization.md) | [EN](examples/en/portfolio_optimization.md))\n  - Investment portfolios, retirement planning, risk management\n\n### How to Use Examples\n1. **For LLM Integration**: Copy the prompt text and provide it to your LLM with MCP Optimizer access\n2. **For Direct API Usage**: Use the provided API structures directly with MCP Optimizer functions\n3. **For Learning**: Understand different optimization problem types and formulations\n\nEach example includes:\n- Problem descriptions and real-world scenarios\n- Ready-to-use prompts for LLMs\n- Technical API structures\n- Common activation phrases\n- Practical applications\n\n## 🔄 Recent Updates\n\n### Latest Release Features:\n1. **Function Exports** - Added exportable functions to all tool modules:\n   - `solve_linear_program()` in linear_programming.py\n   - `solve_assignment_problem()` in assignment.py  \n   - `solve_knapsack_problem()` in knapsack.py\n   - `optimize_portfolio()` in financial.py\n   - `optimize_production()` in production.py\n\n2. **Enhanced Testing** - Updated comprehensive test suite with correct function signatures\n\n3. **OR-Tools Integration** - Confirmed full functionality of all OR-Tools components\n\n## 🚀 Fully Automated Release Process\n\n### New Simplified Git Flow (3 steps!)\nThe project uses a fully automated release process:\n\n#### 1. Create Release Branch\n```bash\n# For minor release (auto-increment)\nuv run python scripts/release.py --type minor\n\n# For specific version\nuv run python scripts/release.py 0.2.0\n\n# For hotfix\nuv run python scripts/release.py --hotfix --type patch\n\n# Preview changes\nuv run python scripts/release.py --type minor --dry-run\n```\n\n#### 2. Create PR to main\n```bash\n# Create PR: release/v0.3.0 → main\ngh pr create --base main --head release/v0.3.0 --title \"Release v0.3.0\"\n```\n\n#### 3. Merge PR - DONE! 🎉\nAfter PR merge, automatically happens:\n- ✅ Create tag v0.3.0\n- ✅ Publish to PyPI\n- ✅ Publish Docker images  \n- ✅ Create GitHub Release\n- ✅ Merge main back to develop\n- ✅ Cleanup release branch\n\n**NO NEED** to run `manual_finalize_release.py` manually anymore!\n\n\u003e 🔒 **Secure Detection**: Uses hybrid approach combining GitHub branch protection with automated release detection. See [Release Process](.github/RELEASE_PROCESS.md) for details.\n\n### Automated Release Pipeline\nThe CI/CD pipeline automatically handles:\n- ✅ **Release Candidates**: Built from `release/*` branches\n- ✅ **Production Releases**: Triggered by version tags on `main`\n- ✅ **PyPI Publishing**: Automatic on tag creation\n- ✅ **Docker Images**: Multi-architecture builds\n- ✅ **GitHub Releases**: With artifacts and release notes\n\n### CI/CD Pipeline\nThe GitHub Actions workflow automatically:\n- ✅ Runs tests on Python 3.11 and 3.12\n- ✅ Performs security scanning\n- ✅ Builds and pushes Docker images\n- ✅ Publishes to PyPI on tag creation\n- ✅ Creates GitHub releases\n\n### Requirements for PyPI Publication\n- Set `PYPI_API_TOKEN` secret in GitHub repository\n- Ensure all tests pass\n- Follow semantic versioning\n\n## 🛠️ Development Tools\n\n### Debug Tools\nUse the debug script to inspect MCP server structure:\n\n```bash\n# Run debug tools to check server structure\nuv run python scripts/debug_tools.py\n\n# This will show:\n# - Available MCP tools\n# - Tool types and attributes\n# - Server configuration\n```\n\n### Comprehensive Testing\nRun the full integration test suite:\n\n```bash\n# Run comprehensive tests\nuv run python tests/test_integration/comprehensive_test.py\n\n# This tests:\n# - All optimization tools (9 categories)\n# - Server health and functionality\n# - Performance benchmarks\n# - End-to-end workflows\n```\n\n### Docker Build Instructions\n\n#### Image Details\n- **Base**: Python 3.12 Slim (Debian-based)\n- **Size**: ~649MB (optimized with multi-stage builds)\n- **Architecture**: Multi-platform support (x86_64, ARM64)\n- **Security**: Non-root user, minimal dependencies\n- **Performance**: Optimized Python bytecode, cleaned build artifacts\n\n#### Local Build Commands\n```bash\n# Standard build\ndocker build -t mcp-optimizer:latest .\n\n# Build with development dependencies\ndocker build --build-arg ENV=development -t mcp-optimizer:dev .\n\n# Build with cache mount for faster rebuilds\ndocker build --mount=type=cache,target=/build/.uv -t mcp-optimizer .\n\n# Check image size\ndocker images mcp-optimizer\n\n# Run container\ndocker run -p 8000:8000 mcp-optimizer:latest\n\n# For development with volume mounting\ndocker run -p 8000:8000 -v $(pwd):/app mcp-optimizer:latest\n\n# Test container functionality\ndocker run --rm mcp-optimizer:latest python -c \"from mcp_optimizer.mcp_server import create_mcp_server; print('✅ MCP Optimizer works!')\"\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Git Flow Policy\nThis project follows a standard Git Flow workflow:\n- **Feature branches** → `develop` branch\n- **Release branches** → `main` branch  \n- **Hotfix branches** → `main` and `develop` branches\n\n📚 **Documentation**:\n- [Contributing Guide](CONTRIBUTING.md) - Complete development workflow and Git Flow policy\n- [Release Process](.github/RELEASE_PROCESS.md) - How releases are created and automated\n- [Repository Setup](.github/REPOSITORY_SETUP.md) - Complete setup guide including branch protection and security configuration\n\n### Development Setup\n```bash\n# Clone and setup\ngit clone https://github.com/dmitryanchikov/mcp-optimizer.git\ncd mcp-optimizer\n\n# Create feature branch from develop\ngit checkout develop\ngit checkout -b feature/your-feature-name\n\n# Install dependencies\nuv sync --extra dev\n\n# Run tests\nuv run pytest tests/ -v\n\n# Run linting\nuv run ruff check src/\nuv run mypy src/\n\n# Create PR to develop branch (not main!)\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [OR-Tools](https://developers.google.com/optimization) - Google's optimization tools\n- [PuLP](https://coin-or.github.io/pulp/) - Linear programming in Python\n- [FastMCP](https://github.com/jlowin/fastmcp) - Fast MCP server implementation\n\n## 📞 Support\n\n- 📧 Email: support@mcp-optimizer.com\n- 🐛 Issues: [GitHub Issues](https://github.com/dmitryanchikov/mcp-optimizer/issues)\n- 📖 Documentation: [docs/](docs/)\n\n---\n\n**Made with ❤️ for the optimization community**\n\n## 📊 Docker Image Size Analysis\n\nThe MCP Optimizer Docker image has been optimized to balance functionality and size:\n\n| Component | Size | % of Total | Description |\n|-----------|------|------------|-------------|\n| **Python packages (/venv)** | **237.0 MB** | **42.8%** | Virtual environment with dependencies |\n| **System libraries (/usr)** | **173.2 MB** | **31.3%** | Base Debian system + Python |\n| **Other** | **137.4 MB** | **24.8%** | Base image, filesystem |\n| **Configuration (/var, /etc)** | **6.2 MB** | **1.1%** | System settings |\n| **Application code (/code)** | **0.2 MB** | **0.04%** | MCP Optimizer source code |\n\n### Key Dependencies by Size\n- **OR-Tools**: 75.0 MB (27.8% of venv) - Critical optimization solver (requires pandas + numpy)\n- **pandas**: 45.0 MB (16.7% of venv) - Required by OR-Tools for data operations\n- **NumPy**: 24.0 MB (8.9% of venv) - Required by OR-Tools for numerical computing\n- **PuLP**: 34.9 MB (12.9% of venv) - Linear programming solver  \n- **FastMCP**: 15.2 MB (5.6% of venv) - MCP server framework\n- **Pydantic**: 12.8 MB (4.7% of venv) - Data validation\n\n### Dependencies Analysis\n- **Core packages cannot be reduced further**: OR-Tools (our main optimization engine) requires both pandas and numpy as mandatory dependencies\n- **Optional examples moved**: Additional packages for examples (streamlit, plotly) moved to `[examples]` extra\n- **Minimal core impact**: Moving examples to optional dependencies only affects development/demo usage\n\n### Image Optimization\n- **Current optimized size**: ~420MB\n- **Core functionality**: Includes all necessary dependencies for production optimization\n- **Example support**: Install with `[examples]` extra for additional demo functionality\n- **OR-Tools constraint**: Cannot remove pandas/numpy due to hard dependency requirements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitryanchikov%2Fmcp-optimizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmitryanchikov%2Fmcp-optimizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitryanchikov%2Fmcp-optimizer/lists"}