╭─╮╭┬╮╶┬╴   ╭─╮╷ ╷╶┬╮╭─╮╷╭ ╷ ╷
╰─╮│││ │    ╰─╮│ │ │││ │├┴╮│ │
╰─╯╵ ╵ ╵    ╰─╯╰─╯╶┴╯╰─╯╵ ╵╰─╯

smt-sudoku-mcp

Теперь ваши агенты могут уверенно играть в судоку!

MCP-сервер, демонстрирующий мощь решения задач по модулю теорий (SMT) с помощью Z3 на классической задаче удовлетворения ограничений — судоку.

Судоку естественным образом отображается на примитивы SMT: генерация головоломки означает поиск модели, удовлетворяющей ограничениям судоку, а затем доказательство того, что уменьшенный набор подсказок по-прежнему имеет единственное решение; проверка сетки означает проверку тех же ограничений на заданных значениях ячеек; решение головоломки означает поиск модели или доказательство её отсутствия.

Инструменты

Все четыре инструмента не имеют состояния: каждый вызов явно принимает и/или возвращает полную сетку, без какого-либо состояния на стороне сервера.

Сетка судоку представляется как {"rows": [[...9 ints...], ...9 rows...]}, где каждая ячейка равна 1-9 для заданной цифры или 0 для пустой ячейки. Любой результат инструмента, который называет конкретную ячейку (конфликт), сообщает row/col с индексацией от 1, что соответствует общепринятому описанию ячеек судоку в тексте (строка 1, столбец 1 — верхняя левая ячейка).

generate_sudoku_puzzle

Генерирует новую судоку-головоломку с единственным решением.

• Вход: difficulty — одно из "easy", "medium" или "hard" (по умолчанию "medium"), соответствующее приблизительному целевому количеству подсказок.

• Выход: {"puzzle": <grid>, "difficulty": <str>, "givens": <int>} — givens — фактическое количество заполненных ячеек, которое может быть немного выше целевого, если удаление дополнительных ячеек нарушило бы единственность.

validate_partial_sudoku_solution

Проверяет, свободна ли частично заполненная сетка от конфликтов, и если да, можно ли её ещё завершить.

• Вход: grid — частичная сетка (0 для пустых ячеек).

• Выход: {"has_conflicts": <bool>, "conflicts": [<cell>, ...], "is_completable": <bool | null>} — is_completable равен null при наличии конфликтов, поскольку вопрос о завершимости не имеет смысла, пока они не разрешены.

validate_full_sudoku_solution

Проверяет, является ли полностью заполненная сетка правильным решением судоку.

• Вход: grid — ожидается, что в ней нет пустых ячеек.

• Выход: {"is_valid": <bool>, "has_empty_cells": <bool>, "conflicts": [<cell>, ...]}.

solve_sudoku_puzzle

Решает нерешённую сетку или сообщает, почему её невозможно решить.

• Вход: grid — частичная сетка для решения (0 для пустых ячеек).

• Выход: {"status": "satisfiable" | "conflicting_givens" | "unsatisfiable", "solution": <grid | null>, "conflicts": [<cell>, ...]}. conflicts заполняется только когда status равен "conflicting_givens" (две заданные ячейки напрямую нарушают правило строки/столбца/блока); "unsatisfiable" означает, что заданные ячейки попарно не конфликтуют, но завершение не существует.

Related MCP server: Gurddy MCP Server

Установка

Требуется Python 3.13+. Пакет опубликован на PyPI.

Самый простой способ запустить его — с помощью uvx, который при первом использовании загружает пакет во временное окружение и не требует отдельного шага установки:

uvx smt-sudoku-mcp

В качестве альтернативы установите его с помощью pip (или uv pip) и запустите установленный консольный скрипт напрямую:

pip install smt-sudoku-mcp
smt-sudoku-mcp

Чтобы работать с исходным кодом, а не с опубликованным пакетом, см. раздел Разработка ниже.

Использование с MCP-клиентом

Этот сервер по умолчанию работает с MCP через stdio, поэтому любой MCP-клиент, который может запустить подпроцесс, может использовать его без дополнительной настройки. Установите SMT_SUDOKU_MCP_TRANSPORT=streamable-http, если клиенту нужно обращаться к отдельному HTTP-сервису; см. Конфигурация.

Claude Code

claude mcp add smt-sudoku -- uvx smt-sudoku-mcp

Claude Desktop

Добавьте запись в разделе Настройки → Разработчик → Изменить конфигурацию (claude_desktop_config.json):

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

Другие MCP-клиенты и агентные фреймворки

Любой клиент, принимающий сырое определение MCP-сервера — Cursor, Windsurf, VS Code или пользовательский агент на основе MCP SDK — может использовать ту же пару command/args: uvx и ["smt-sudoku-mcp"]. Для streamable-http запустите сервер отдельно с SMT_SUDOKU_MCP_TRANSPORT=streamable-http uvx smt-sudoku-mcp и укажите клиенту адрес http://<host>:<port>/mcp вместо команды для запуска.

После подключения агент может вызывать четыре указанных выше инструмента так же, как и любой другой. Например, просьба агенту «сгенерировать сложную судоку-головоломку, затем решить её и проверить решение» приведёт к последовательному вызову generate_sudoku_puzzle, solve_sudoku_puzzle и validate_full_sudoku_solution без дополнительных указаний, поскольку описания и схемы каждого инструмента достаточны для того, чтобы агент сам спланировал последовательность.

Конфигурация

Переменные окружения, все необязательные:

Разработка

Чтобы запустить сервер из исходников вместо опубликованного пакета, используйте uv:

uv sync
uv run smt-sudoku-mcp

См. AGENTS.md с заметками по архитектуре и полным набором команд разработки (just -l).

Вклад

Приветствуются сообщения об ошибках и pull request'ы.

Лицензия

MIT.