gurddy mcp

Gurddy MCP Сервер

Комплексный сервер Model Context Protocol (MCP) для решения задач удовлетворения ограничений (CSP), линейного программирования (LP), минимаксной оптимизации и продвинутых задач оптимизации на базе SciPy. Построен на библиотеке оптимизации gurddy с интеграцией SciPy, поддерживает решение различных классических задач через два транспорта MCP: stdio (для интеграции с IDE) и потоковый HTTP (для веб-клиентов).

🚀 Быстрый старт (Stdio): pip install gurddy_mcp, затем настройте в вашей IDE

🌐 Быстрый старт (HTTP): docker run -p 8080:8080 gurddy-mcp или смотрите руководство по развертыванию

📦 Пакет PyPI: https://pypi.org/project/gurddy_mcp

Основные возможности

🎯 Решение задач CSP

• Задача о N ферзях: Разместите N ферзей на доске N×N без атак
• Раскраска графа: Назначьте цвета вершинам так, чтобы смежные вершины различались
• Раскраска карты: Раскрасьте географические регионы так, чтобы смежные регионы различались
• Решатель Судоку: Решайте стандартные головоломки Судоку 9×9
• Логические головоломки: Загадка Эйнштейна «Зебра» и пользовательские логические задачи
• Планирование: Составление расписания курсов, встреч, распределение ресурсов
• Общий решатель CSP: Поддержка пользовательских задач удовлетворения ограничений

📊 Задачи ЛП/Оптимизации

• Линейное программирование: Оптимизация непрерывных переменных с линейными ограничениями
• Смешанное целочисленное программирование: Оптимизация с целочисленными и непрерывными переменными
• Планирование производства: Оптимизация производства с ограниченными ресурсами и анализом чувствительности
• Оптимизация портфеля: Распределение инвестиций с учетом ограничений риска
• Транспортные задачи: Оптимизация цепочек поставок и логистики

🎮 Минимакс/Теория игр

• Игры с нулевой суммой: Решение игр двух игроков («Камень-ножницы-бумага», «Орлянка», «Битва полов»)
• Равновесия Нэша в смешанных стратегиях: Поиск оптимальных вероятностных стратегий
• Робастная оптимизация: Минимизация наихудших потерь в условиях неопределенности
• Максиминные решения: Максимизация наихудшего выигрыша (консервативные стратегии)
• Игры безопасности: Распределение ресурсов защитника и атакующего
• Робастный портфель: Минимизация максимальных потерь по рыночным сценариям
• Планирование производства: Консервативные производственные решения (максимизация минимальной прибыли)
• Рекламная конкуренция: Игры за долю рынка и конкурентные стратегии

🔬 Интеграция SciPy

• Нелинейная оптимизация портфеля: Квадратичные модели риска с оптимизацией SciPy
• Оценка статистических параметров: Подгонка распределений с ограничениями (МП, сопоставление квантилей)
• Оптимизация обработки сигналов: Проектирование КИХ-фильтров с оптимизацией частотной характеристики
• Гибридный CSP-SciPy: Дискретный выбор объектов + непрерывная оптимизация мощностей
• Численное интегрирование: Задачи оптимизации, включающие интегралы и сложные функции

🧮 Классические математические задачи

• Игра «24 очка»: Поиск арифметических выражений для получения 24 из четырех чисел
• Задача о курах и кроликах: Классическая задача с ограничениями по головам и ногам
• Мини-судоку: Решатель Судоку 4×4 с использованием методов CSP
• Задача о 4 ферзях: Упрощенная задача о N ферзях для образовательных целей
• Рюкзак 0-1: Классическая задача оптимизации с ограничениями по весу и ценности

🔌 Поддержка протокола MCP

• Транспорт Stdio: Локальная интеграция с IDE (Kiro, Claude Desktop, Cline и др.)
• Потоковый HTTP-транспорт: Веб-клиенты и удаленный доступ с опциональной потоковой передачей
• Единый интерфейс: Одни и те же инструменты для обоих транспортов
• JSON-RPC 2.0: Полное соответствие протоколу
• Автоодобрение: Настройка доверенных инструментов для беспрепятственного выполнения

Установка

Из PyPI (рекомендуется)

# Install the latest stable version
pip install gurddy_mcp

# Or install with development dependencies
pip install gurddy_mcp[dev]

Из исходников

# Clone the repository
git clone https://github.com/novvoo/gurddy-mcp.git
cd gurddy-mcp

# Install in development mode
pip install -e .

Проверка установки

# Test MCP stdio server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | gurddy-mcp

Использование

1. Сервер MCP Stdio (основной интерфейс)

Основная команда gurddy-mcp — это сервер MCP stdio, который можно интегрировать с такими инструментами, как Kiro.

Вариант A: Использование uvx (рекомендуется — всегда последняя версия)

Использование uvx гарантирует, что вы всегда запускаете последнюю опубликованную версию без ручной установки.

Настройка в ~/.kiro/settings/mcp.json или .kiro/settings/mcp.json:

Рекомендуется: Явное указание последней версии

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example",
        "info",
        "install",
        "solve_n_queens",
        "solve_sudoku",
        "solve_graph_coloring",
        "solve_map_coloring",
        "solve_lp",
        "solve_production_planning",
        "solve_minimax_game",
        "solve_minimax_decision",
        "solve_24_point_game",
        "solve_chicken_rabbit_problem",
        "solve_scipy_portfolio_optimization",
        "solve_scipy_statistical_fitting",
        "solve_scipy_facility_location"
      ]
    }
  }
}

Альтернатива: Без указания версии (также используется последняя)

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Привязка к конкретной версии (при необходимости)

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp==<VERSION>"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Зачем использовать uvx?

• ✅ Всегда автоматически запускает последнюю опубликованную версию
• ✅ Не требует ручной установки или обновления
• ✅ Изолированное окружение для каждого выполнения
• ✅ Отсутствие конфликтов зависимостей с системным Python

Предварительные требования: Установите uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Вариант B: Использование прямой команды (после установки)

Если вы уже установили gurddy-mcp через pip:

{
  "mcpServers": {
    "gurddy": {
      "command": "gurddy-mcp",
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Доступные инструменты MCP (всего 16):

• info — Получить информацию о сервере gurddy MCP и его возможностях
• install — Установить или обновить пакет gurddy
• run_example — Запустить примеры программ (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems и др.)
• solve_n_queens — Решить задачу о N ферзях для любого размера доски
• solve_sudoku — Решить головоломки Судоку 9×9 с использованием CSP
• solve_graph_coloring — Решить задачу раскраски графа с настраиваемыми цветами
• solve_map_coloring — Решить задачи раскраски карт (например, Австралия, США)
• solve_lp — Решить задачу линейного программирования (ЛП) или смешанного целочисленного программирования (СЦП)
• solve_production_planning — Оптимизация производства с опциональным анализом чувствительности
• solve_minimax_game — Игры двух игроков с нулевой суммой (поиск равновесий Нэша)
• solve_minimax_decision — Робастная оптимизация (минимизация максимальных потерь или максимизация минимального выигрыша)
• solve_24_point_game — Решить игру «24 очка» с четырьмя числами, используя арифметические операции
• solve_chicken_rabbit_problem — Решить классическую задачу о курах и кроликах с ограничениями по головам и ногам
• solve_scipy_portfolio_optimization — Решить задачу нелинейной оптимизации портфеля с использованием SciPy
• solve_scipy_statistical_fitting — Решить задачу оценки статистических параметров с использованием SciPy
• solve_scipy_facility_location — Решить задачу размещения объектов с использованием гибридного подхода CSP-SciPy

Тестирование сервера MCP:

# Test initialization
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | gurddy-mcp

# Test listing tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | gurddy-mcp

# Test info tools
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"info","arguments":{"":""}}}' | gurddy-mcp |jq 

# Test run example tools
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"run_example","arguments":{"example":"n_queens"}}}' | gurddy-mcp |jq

# Test sudoku tools
cat <<EOF | tr -d '\n'|gurddy-mcp|jq
{"jsonrpc":"2.0","id":123,"method":"tools/call","params":{
  "name":"solve_sudoku",
  "arguments":{
    "puzzle":[
      [5,3,0,0,7,0,0,0,0],
      [6,0,0,1,9,5,0,0,0],
      [0,9,8,0,0,0,0,6,0],
      [8,0,0,0,6,0,0,0,3],
      [4,0,0,8,0,3,0,0,1],
      [7,0,0,0,2,0,0,0,6],
      [0,6,0,0,0,0,2,8,0],
      [0,0,0,4,1,9,0,0,5],
      [0,0,0,0,8,0,0,7,9]
    ]
  }
}}
EOF

2. HTTP-сервер MCP

Запуск HTTP-сервера MCP (протокол MCP через потоковый HTTP):

Локальная разработка:

uvicorn mcp_server.mcp_http_server:app --host 127.0.0.1 --port 8080

Docker:

# Build the image
docker build -t gurddy-mcp .

# Run the container
docker run -p 8080:8080 gurddy-mcp

Доступ к серверу:

• Корень: http://127.0.0.1:8080/
• Проверка работоспособности: http://127.0.0.1:8080/health
• HTTP-транспорт: http://127.0.0.1:8080/mcp/http (POST — поддерживает как обычный, так и потоковый режим)

Тестирование HTTP-сервера MCP:

HTTP-транспорт (без потоковой передачи):

# List available tools
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"info","arguments":{}}}'

HTTP-транспорт (потоковая передача с заголовком Accept):

# List tools with streaming response
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool with streaming response
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"solve_n_queens","arguments":{"n":4}}}'

HTTP-транспорт (потоковая передача с заголовком X-Stream):

# Alternative way to enable streaming
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "X-Stream: true" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"info","arguments":{}}}'

Пример клиента на Python:

• examples/streamable_http_client.py — Клиент HTTP-транспорта с примерами потоковой передачи

Инструменты MCP

Сервер предоставляет следующие инструменты MCP:

info

Получить информацию о пакете gurddy.

{
  "name": "info",
  "arguments": {}
}

install

Установить или обновить пакет gurddy.

{
  "name": "install",
  "arguments": {
    "package": "gurddy",
    "upgrade": false
  }
}

run_example

Запустить пример gurddy.

{
  "name": "run_example",
  "arguments": {
    "example": "n_queens"
  }
}

Доступные примеры: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Решить задачу о N ферзях.

{
  "name": "solve_n_queens",
  "arguments": {
    "n": 8
  }
}

solve_sudoku

Решить головоломку Судоку 9x9.

{
  "name": "solve_sudoku",
  "arguments": {
    "puzzle": [[5,3,0,...], [6,0,0,...], ...]
  }
}

solve_graph_coloring

Решить задачу раскраски графа.

{
  "name": "solve_graph_coloring",
  "arguments": {
    "edges": [[0,1], [1,2], [2,0]],
    "num_vertices": 3,
    "max_colors": 3
  }
}

solve_map_coloring

Решить задачу раскраски карты.

{
  "name": "solve_map_coloring",
  "arguments": {
    "regions": ["A", "B", "C"],
    "adjacencies": [["A", "B"], ["B", "C"]],
    "max_colors": 2
  }
}

solve_lp

Решить задачу линейного программирования (ЛП) или смешанного целочисленного программирования (СЦП) с использованием PuLP.

{
  "name": "solve_lp",
  "arguments": {
    "profits": {
      "ProductA": 30,
      "ProductB": 40
    },
    "consumption": {
      "ProductA": {"Labor": 2, "Material": 3},
      "ProductB": {"Labor": 3, "Material": 2}
    },
    "capacities": {
      "Labor": 100,
      "Material": 120
    },
    "integer": true
  }
}

solve_production_planning

Решить задачу оптимизации планирования производства с опциональным анализом чувствительности.

{
  "name": "solve_production_planning",
  "arguments": {
    "profits": {
      "ProductA": 30,
      "ProductB": 40
    },
    "consumption": {
      "ProductA": {"Labor": 2, "Material": 3},
      "ProductB": {"Labor": 3, "Material": 2}
    },
    "capacities": {
      "Labor": 100,
      "Material": 120
    },
    "integer": true,
    "sensitivity_analysis": false
  }
}

solve_minimax_game

Решить игру двух игроков с нулевой суммой, используя минимакс (теория игр).

{
  "name": "solve_minimax_game",
  "arguments": {
    "payoff_matrix": [
      [0, -1, 1],
      [1, 0, -1],
      [-1, 1, 0]
    ],
    "player": "row"
  }
}

Возвращает оптимальную смешанную стратегию и цену игры для указанного игрока.

solve_minimax_decision

Решить задачу принятия решений по минимаксу в условиях неопределенности (робастная оптимизация).

{
  "name": "solve_minimax_decision",
  "arguments": {
    "scenarios": [
      {"A": -0.2, "B": -0.1, "C": 0.05},
      {"A": 0.3, "B": 0.2, "C": -0.02},
      {"A": 0.05, "B": 0.03, "C": -0.01}
    ],
    "decision_vars": ["A", "B", "C"],
    "budget": 100.0,
    "objective": "minimize_max_loss"
  }
}

Цели: minimize_max_loss (робастный портфель) или maximize_min_gain (консервативное производство)

solve_24_point_game

Решить игру «24 очка» с четырьмя числами, используя арифметические операции.

{
  "name": "solve_24_point_game",
  "arguments": {
    "numbers": [1, 2, 3, 4]
  }
}

Находит арифметические выражения с использованием +, -, *, / и скобок для получения ровно 24.

solve_chicken_rabbit_problem

Решить классическую задачу о курах и кроликах с ограничениями по головам и ногам.

{
  "name": "solve_chicken_rabbit_problem",
  "arguments": {
    "total_heads": 35,
    "total_legs": 94
  }
}

Определяет количество кур (2 ноги) и кроликов (4 ноги) при заданном общем количестве голов и ног.

solve_scipy_portfolio_optimization

Решить задачу нелинейной оптимизации портфеля с использованием SciPy и квадратичных моделей риска.

{
  "name": "solve_scipy_portfolio_optimization",
  "arguments": {
    "expected_returns": [0.12, 0.18, 0.15],
    "covariance_matrix": [
      [0.04, 0.01, 0.02],
      [0.01, 0.09, 0.03],
      [0.02, 0.03, 0.06]
    ],
    "risk_tolerance": 1.0
  }
}

Оптимизирует веса портфеля для максимизации доходности за вычетом штрафа за риск, используя оптимизацию среднего и дисперсии.

solve_scipy_statistical_fitting

Решить задачу оценки статистических параметров с использованием SciPy и подгонки распределений.

{
  "name": "solve_scipy_statistical_fitting",
  "arguments": {
    "data": [1.2, 2.3, 1.8, 2.1, 1.9, 2.4, 1.7, 2.0],
    "distribution": "normal"
  }
}

Подгоняет статистические распределения («нормальное», «экспоненциальное», «равномерное») к данным и предоставляет тесты на согласие.

solve_scipy_facility_location

Решить задачу размещения объектов с использованием гибридного подхода CSP-SciPy.

{
  "name": "solve_scipy_facility_location",
  "arguments": {
    "customer_locations": [[0, 0], [10, 10], [5, 15]],
    "customer_demands": [100, 150, 80],
    "facility_locations": [[2, 3], [8, 12], [6, 8]],
    "max_facilities": 2,
    "fixed_cost": 100.0
  }
}

Объединяет дискретный выбор объектов (CSP) с непрерывной оптимизацией мощностей (SciPy) для минимизации общих затрат.

Развертывание в Docker

Сборка и запуск

# Build the image
docker build -t gurddy-mcp .

# Run the container
docker run -p 8080:8080 gurddy-mcp

# Or with environment variables
docker run -p 8080:8080 -e PORT=8080 gurddy-mcp

Docker Compose

version: '3.8'
services:
  gurddy-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - PYTHONUNBUFFERED=1
    restart: unless-stopped

Пример вывода

Задача о N ферзях

POST /solve-n-queens
{
"n": 8
}

Структура проекта

mcp_server/
├── handlers/
│   └── gurddy.py           # Core solver implementation (16 MCP tools)
│                          # - solve_24_point_game, solve_chicken_rabbit_problem
│                          # - solve_scipy_portfolio_optimization, solve_scipy_statistical_fitting
│                          # - solve_scipy_facility_location, and 11 other solvers
├── tools/                  # MCP tool wrappers
├── examples/               # Rich Problem Examples
│   ├── n_queens.py         # N-Queens Problem
│   ├── graph_coloring.py   # Graph Coloring Problem
│   ├── map_coloring.py     # Map Coloring Problem
│   ├── logic_puzzles.py    # Logic Puzzles
│   ├── scheduling.py       # Scheduling Problem
│   ├── scipy_optimization.py # SciPy Integration Examples
│   │                      # - Portfolio optimization, statistical fitting, facility location
│   ├── classic_problems.py # Classic Math Problems
│   │                      # - 24-point game, chicken-rabbit problem, mini sudoku
│   ├── optimized_csp.py    # Advanced CSP techniques
│   ├── optimized_lp.py     # Linear programming examples
│   └── minimax.py          # Game theory and robust optimization
├── mcp_stdio_server.py     # MCP Stdio Server (for IDE integration)
└── mcp_http_server.py      # MCP HTTP Server (for web clients)

examples/
└── http_mcp_client.py      # Example HTTP MCP client

Dockerfile                  # Docker configuration for HTTP server

Транспорты MCP

Транспорт	Команда	Протокол	Вариант использования
Stdio	gurddy-mcp	MCP через stdin/stdout	Интеграция с IDE (Kiro, Claude Desktop и др.)
Потоковый HTTP	uvicorn mcp_server.mcp_http_server:app	MCP через HTTP с опциональной потоковой передачей	Веб-клиенты, удаленный доступ, развертывание в Docker

Все транспорты реализуют один и тот же протокол MCP и предоставляют идентичные инструменты.

Возможности HTTP-транспорта

HTTP-транспорт (конечная точка /mcp/http):

• Одиночный шаблон запрос-ответ
• Опциональная потоковая передача: добавьте заголовок Accept: text/event-stream или X-Stream: true
• Проще для разовых запросов
• Совместимость со стандартными HTTP-клиентами
• Отсутствие состояния соединения для управления
• Поддерживает как обычные JSON-ответы, так и потоковые ответы в формате SSE

Пример вывода

Задача о N ферзях

$ gurddy-mcp-cli run-example n_queens

Solving 8-Queens problem...

8-Queens Solution:
+---+---+---+---+---+---+---+---+
| Q |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   | Q |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   | Q |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   | Q |   |   |
+---+---+---+---+---+---+---+---+
|   |   | Q |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   | Q |   |
+---+---+---+---+---+---+---+---+
|   | Q |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | Q |   |   |   |   |
+---+---+---+---+---+---+---+---+
Queen positions: (0,0), (1,4), (2,7), (3,5), (4,2), (5,6), (6,1), (7,3)

Логические головоломки

$ python -m mcp_server.server run-example logic_puzzles

Solving Simple Logic Puzzle:
Solution:
Position 1: Alice has Cat in Green house
Position 2: Bob has Dog in Red house  
Position 3: Carol has Fish in Blue house

Solving the Famous Zebra Puzzle (Einstein's Riddle)...
ANSWERS:
Who owns the zebra? Ukrainian (House 5)
Who drinks water? Japanese (House 2)

Примеры HTTP API

Решение классических задач

Раскраска карты Австралии

import requests

response = requests.post("http://127.0.0.1:8080/solve-map-coloring", json={ 
"regions": ['WA', 'NT', 'SA', 'QLD', 'NSW', 'VIC', 'TAS'], 
"adjacencies": [ 
['WA', 'NT'], ['WA', 'SA'], ['NT', 'SA'], ['NT', 'QLD'], 
['SA', 'QLD'], ['SA', 'NSW'], ['SA', 'VIC'], 
['QLD', 'NSW'], ['NSW', 'VIC'] 
], 
"max_colors": 4
})

Задача о 8 ферзях

response = requests.post("http://127.0.0.1:8080/solve-n-queens",
json={"n": 8})

Доступные примеры

Все примеры можно запустить с помощью gurddy-mcp run-example <name> или python -m mcp_server.server run-example <name>:

Примеры CSP ✅

• n_queens — Задача о N ферзях (4, 6, 8 ферзей с визуальным отображением доски)
• graph_coloring — Раскраска графа (треугольник, квадрат, граф Петерсена, колесо)
• map_coloring — Раскраска карты (Австралия, западные штаты США, Европа)
• scheduling — Задачи планирования (расписание курсов, встреч, распределение ресурсов)
• logic_puzzles — Логические головоломки (простая логическая задача, загадка Эйнштейна «Зебра»)
• optimized_csp — Продвинутые методы CSP (решатель Судоку)

Примеры ЛП ✅

• lp / optimized_lp — Примеры линейного программирования:
  • Оптимизация портфеля с ограничениями риска
  • Транспортная задача (оптимизация цепочки поставок)
  • Анализ ослабления ограничений
  • Сравнение производительности для задач разного размера

Примеры минимакса ✅

• minimax — Минимаксная оптимизация и теория игр:
  • «Камень-ножницы-бумага» (игра с нулевой суммой)
  • «Орлянка» (координационная игра)
  • «Битва полов» (равновесие в смешанных стратегиях)
  • Робастная оптимизация портфеля (минимизация максимальных потерь)
  • Планирование производства (максимизация минимальной прибыли)
  • Распределение ресурсов безопасности (игра защитник-атакующий)
  • Рекламная конкуренция (игра за долю рынка)

Примеры интеграции со SciPy ✅

• scipy_optimization - Продвинутая оптимизация с помощью SciPy:
  • Нелинейная портфельная оптимизация с квадратичными моделями риска
  • Статистическая оценка параметров (подгонка распределений с ограничениями)
  • Оптимизация обработки сигналов (проектирование КИХ-фильтров)
  • Гибридное размещение объектов CSP-SciPy (дискретная + непрерывная оптимизация)
  • Численное интегрирование в целевых функциях оптимизации

Классические математические задачи ✅

• classic_problems - Решение учебных математических задач:
  • Игра «24 очка» (арифметические выражения для получения 24)
  • Задача о курах и кроликах (классическое удовлетворение ограничений)
  • Мини-судоку 4×4 (упрощённая демонстрация CSP)
  • Задача о 4 ферзях (учебный вариант задачи о N ферзях)
  • Задача о рюкзаке 0-1 (классическая оптимизация)

Поддерживаемые типы задач

🧩 Задачи CSP

• N-Queens: Классическая задача о N ферзях для доски любого размера (N=4 до N=100+)
• Раскраска графа: Раскраска вершин произвольных графов (треугольник, Петерсена, колесо и др.)
• Раскраска карты: Раскраска географических регионов (карты Австралии, США, Европы)
• Судоку: Стандартные судоку 9×9 с распространением ограничений
• Логические головоломки: Загадка Эйнштейна «Зебра» и пользовательские задачи логического вывода
• Планирование: Составление расписания курсов, переговорных комнат, распределение ресурсов с временными ограничениями

📈 Задачи оптимизации

• Линейное программирование: Оптимизация непрерывных переменных с линейными ограничениями
• Целочисленное программирование: Оптимизация дискретных переменных (объёмы производства, назначения)
• Смешанное целочисленное программирование: Комбинация непрерывных и дискретных переменных
• Планирование производства: Многопродуктовая оптимизация с ограниченными ресурсами
• Портфельная оптимизация: Распределение инвестиций с ограничениями по риску и доходности
• Транспортная задача: Оптимизация цепочки поставок (от складов к клиентам)

🎲 Теория игр и робастная оптимизация

• Игры с нулевой суммой: «Камень-ножницы-бумага», «Подбрасывание монет», «Битва полов»
• Равновесия Нэша в смешанных стратегиях: Оптимальные вероятностные стратегии для обоих игроков
• Минимаксные решения: Минимизация наихудших потерь в условиях неопределённости
• Максиминные решения: Максимизация наихудшего выигрыша (консервативные стратегии)
• Робастный портфель: Минимизация максимальных потерь при различных рыночных сценариях
• Игры безопасности: Задачи распределения ресурсов «защитник-атакующий»

🔬 Продвинутая оптимизация на базе SciPy

• Нелинейная портфельная оптимизация: Квадратичные модели риска с максимизацией коэффициента Шарпа
• Статистическая оценка параметров: Подгонка распределений методами MLE и квантилей с ограничениями
• Обработка сигналов: Проектирование КИХ-фильтров с оптимизацией частотной характеристики
• Гибридная оптимизация: Сочетание Gurddy CSP с непрерывной оптимизацией SciPy
• Численное интегрирование: Задачи оптимизации, включающие сложные математические функции

🧮 Классические учебные задачи

• Игра «24 очка»: Поиск арифметических выражений из четырёх чисел для получения 24
• Задача о курах и кроликах: Классическое удовлетворение ограничений с головами и ногами
• Мини-судоку: Решение судоку 4×4 с использованием методов CSP
• Варианты задачи о N ферзях: Учебные версии классической задачи
• Задачи о рюкзаке: Оптимизация рюкзака 0-1 с ограничениями по весу и ценности

Функции производительности

• Быстрое решение: Миллисекундный отклик для задач малого и среднего размера (N-Queens N≤12, графы <50 вершин)
• Масштабируемость: Обработка больших задач (N-Queens N=100+, ЛП с 1000+ переменных)
• Эффективность памяти: Поиск с возвратом и распространение ограничений минимизируют использование памяти
• Расширяемость: Пользовательские ограничения, целевые функции и типы задач
• Безопасность параллелизма: HTTP API поддерживает одновременную обработку запросов
• Готовность к эксплуатации: Развёртывание в Docker, проверки работоспособности, обработка ошибок

Тесты производительности

Типичное время выполнения на стандартном оборудовании:

• Примеры CSP: 0.4-0.5 с (N-Queens, раскраска графов, логические головоломки)
• Примеры ЛП: 0.8-0.9 с (портфель, транспортная задача, планирование производства)
• Примеры минимакса: 0.3-0.5 с (решение игр, робастная оптимизация)
• Примеры SciPy: 0.5-1.2 с (нелинейная оптимизация, статистическая подгонка)
• Классические задачи: 0.1-0.3 с (24 очка, куры-кролики, мини-судоку)
• Судоку: <0.1 с для стандартных головоломок 9×9
• Большие N-Queens: ~2-3 с для N=100

Устранение неполадок

Типичные ошибки

• "gurddy package not available": Установите с помощью python -m mcp_server.server install
• "No solution found": Решения при заданных ограничениях не существует; попробуйте ослабить ограничения
• "Invalid input types": Проверьте типы данных входных параметров
• "Unknown example": Используйте python -m mcp_server.server run-example --help, чтобы увидеть доступные примеры

Проблемы установки

# install individually
pip install gurddy pulp>=2.6.0 scipy>=1.9.0 numpy>=1.21.0

# Check installation
python -c "import gurddy, pulp, scipy, numpy; print('All dependencies installed')"

Отладка примеров

Запускайте примеры напрямую для отладки:

# After installing gurddy_mcp
python -c "from mcp_server.examples import n_queens; n_queens.main()"

# Or from source - CSP examples
python mcp_server/examples/n_queens.py
python mcp_server/examples/graph_coloring.py
python mcp_server/examples/logic_puzzles.py
python mcp_server/examples/optimized_csp.py

# LP and optimization examples
python mcp_server/examples/optimized_lp.py

# Game theory and minimax examples
python mcp_server/examples/minimax.py

# SciPy integration examples (includes portfolio, statistical fitting, facility location)
python mcp_server/examples/scipy_optimization.py

# Classic math problems (includes 24-point game, chicken-rabbit problem)
python mcp_server/examples/classic_problems.py

# Test individual MCP tools directly
python -c "from mcp_server.handlers.gurddy import solve_24_point_game; print(solve_24_point_game([1,2,3,4]))"
python -c "from mcp_server.handlers.gurddy import solve_chicken_rabbit_problem; print(solve_chicken_rabbit_problem(35, 94))"
python -c "from mcp_server.handlers.gurddy import solve_scipy_portfolio_optimization; print(solve_scipy_portfolio_optimization([0.12, 0.18], [[0.04, 0.01], [0.01, 0.09]]))"

Требования для интеграции SciPy

Примеры интеграции SciPy требуют дополнительных зависимостей:

# Install SciPy and NumPy 
pip install scipy>=1.9.0 numpy>=1.21.0

# Verify SciPy integration
python -c "import scipy.optimize, numpy; print('SciPy integration ready')"

Примеры SciPy включают:

• Нелинейная портфельная оптимизация: Квадратичные модели риска с максимизацией коэффициента Шарпа
• Статистическая оценка параметров: Подгонка распределений методами MLE и квантилей
• Обработка сигналов: Проектирование КИХ-фильтров с оптимизацией частотной характеристики
• Гибридный CSP-SciPy: Размещение объектов с комбинацией дискретной и непрерывной оптимизации
• Численное интегрирование: Сложные задачи оптимизации, включающие интегралы

Разработка

Архитектура

Проект использует централизованный реестр инструментов с автоматически генерируемыми схемами для обеспечения согласованности между серверами stdio и HTTP:

• Определения инструментов: mcp_server/tool_definitions.py (только базовые метаданные)
• Автоматически генерируемый реестр: mcp_server/tool_registry.py (схемы генерируются из сигнатур функций)
• Сервер Stdio: mcp_server/mcp_stdio_server.py (для интеграции с IDE)
• Сервер HTTP: mcp_server/mcp_http_server.py (для веб-клиентов)
• Обработчики: mcp_server/handlers/gurddy.py (реализации инструментов)
• Генератор схем: scripts/generate_registry.py (автоматически генерирует схемы из сигнатур функций)

Добавление нового инструмента

1. Реализуйте обработчик в mcp_server/handlers/gurddy.py:

   def my_new_tool(param1: str, param2: int = 10) -> Dict[str, Any]:
       """Tool implementation with proper type hints."""
       return {"result": "success"}
   

2. Добавьте базовые метаданные в mcp_server/tool_definitions.py:

   {
       "name": "my_new_tool",
       "function": "my_new_tool",
       "description": "Description of what the tool does",
       "category": "optimization",
       "module": "handlers.gurddy"
   }
   

3. Сгенерируйте схемы и проверьте:

   # Auto-generate schemas from function signatures
   python scripts/generate_registry.py
   
   # Verify consistency
   python scripts/verify_consistency.py
   pytest tests/test_consistency.py -v
   

Вот и всё! Схема автоматически генерируется из аннотаций типов вашей функции, и оба сервера — stdio и HTTP — подхватят новый инструмент.

Пользовательские ограничения

# Define a custom constraint in gurddy
def custom_constraint(var1, var2):
    return var1 + var2 <= 10

model.addConstraint(gurddy.FunctionConstraint(custom_constraint, (var1, var2)))

Тестирование

# Run all tests
pytest

# Run specific test suites
pytest tests/test_consistency.py -v
pytest tests/test_tool_registry.py -v

# Verify tool registry consistency
python scripts/verify_consistency.py

Лицензия

Этот проект лицензирован под открытой лицензией. Подробности см. в файле LICENSE.