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

smt-sudoku-mcp

¡Ahora tus agentes pueden jugar al Sudoku con confianza!

Un servidor MCP que demuestra el poder de la resolución de satisfacibilidad módulo teorías (SMT), usando Z3, a través del clásico rompecabezas de satisfacción de restricciones del Sudoku.

El Sudoku se mapea limpiamente sobre los primitivos de SMT: generar un rompecabezas significa encontrar un modelo que satisfaga las restricciones del Sudoku y luego demostrar que un conjunto reducido de pistas aún tiene una única solución; validar una cuadrícula significa comprobar esas mismas restricciones contra los valores de las celdas dadas; resolver un rompecabezas significa encontrar un modelo o demostrar que no existe ninguno.

Herramientas

Las cuatro herramientas son sin estado: cada llamada toma y/o devuelve una cuadrícula completa explícitamente, sin estado de sesión en el servidor.

Una cuadrícula de Sudoku se representa como {"rows": [[...9 ints...], ...9 rows...]}, donde cada celda es 1-9 para un dígito dado o 0 para una celda vacía. Cualquier resultado de herramienta que nombre una celda específica (un conflicto) informa row/col como indexado desde 1, coincidiendo con cómo se describen convencionalmente las celdas de Sudoku en texto (fila 1, columna 1 es la celda superior izquierda).

generate_sudoku_puzzle

Genera un nuevo rompecabezas de Sudoku con solución única.

• Entrada: difficulty — uno de "easy", "medium" o "hard" (por defecto "medium"), que se asigna a un recuento aproximado de pistas objetivo.

• Salida: {"puzzle": <grid>, "difficulty": <str>, "givens": <int>} — givens es el número real de celdas rellenas, que puede ser ligeramente superior al objetivo si eliminar más celdas hubiera roto la unicidad.

validate_partial_sudoku_solution

Comprueba si una cuadrícula parcialmente rellena está libre de conflictos y, si es así, si aún se puede completar.

• Entrada: grid — una cuadrícula parcial (0 para celdas vacías).

• Salida: {"has_conflicts": <bool>, "conflicts": [<cell>, ...], "is_completable": <bool | null>} — is_completable es null cuando hay conflictos, ya que la completabilidad no es una pregunta significativa hasta que se resuelvan.

validate_full_sudoku_solution

Comprueba si una cuadrícula completamente rellena es una solución correcta de Sudoku.

• Entrada: grid — se espera que no tenga celdas vacías.

• Salida: {"is_valid": <bool>, "has_empty_cells": <bool>, "conflicts": [<cell>, ...]}.

solve_sudoku_puzzle

Resuelve una cuadrícula sin resolver, o informa por qué no se puede resolver.

• Entrada: grid — una cuadrícula parcial para resolver (0 para celdas vacías).

• Salida: {"status": "satisfiable" | "conflicting_givens" | "unsatisfiable", "solution": <grid | null>, "conflicts": [<cell>, ...]}. conflicts solo se rellena cuando status es "conflicting_givens" (dos celdas dadas violan directamente una regla de fila/columna/caja); "unsatisfiable" significa que las pistas son libres de conflictos por pares pero no existe ninguna finalización.

Related MCP server: Gurddy MCP Server

Instalación

Requiere Python 3.13+. El paquete está publicado en PyPI.

La forma más sencilla de ejecutarlo es con uvx, que obtiene el paquete en un entorno efímero en el primer uso y no requiere un paso de instalación separado:

uvx smt-sudoku-mcp

Alternativamente, instálalo con pip (o uv pip) y ejecuta el script de consola instalado directamente:

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

Para trabajar en el código fuente en lugar del paquete publicado, consulta Desarrollo a continuación.

Uso con un cliente MCP

Este servidor habla MCP sobre stdio por defecto, por lo que cualquier cliente MCP que pueda lanzar un subproceso puede usarlo sin configuración adicional. Establece SMT_SUDOKU_MCP_TRANSPORT=streamable-http en su lugar si el cliente necesita acceder a un servicio HTTP independiente; consulta Configuración.

Claude Code

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

Claude Desktop

Añade una entrada en Configuración → Desarrollador → Editar Config (claude_desktop_config.json):

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

Otros clientes MCP y marcos de agentes

Cualquier cliente que acepte una definición de servidor MCP sin procesar — Cursor, Windsurf, VS Code, o un agente personalizado construido sobre un SDK de MCP — puede usar el mismo par command/args: uvx y ["smt-sudoku-mcp"]. Para streamable-http, ejecuta el servidor por separado con SMT_SUDOKU_MCP_TRANSPORT=streamable-http uvx smt-sudoku-mcp y apunta el cliente a http://<host>:<port>/mcp en lugar de darle un comando para lanzar.

Una vez conectado, un agente puede llamar a las cuatro herramientas anteriores como lo haría con cualquier otra herramienta. Por ejemplo, pedir a un agente que "genere un rompecabezas de Sudoku difícil, luego lo resuelva y verifique la solución" encadenará generate_sudoku_puzzle, solve_sudoku_puzzle y validate_full_sudoku_solution sin más orientación, ya que la descripción y el esquema de cada herramienta son suficientes para que el agente planifique la secuencia por sí mismo.

Configuración

Variables de entorno, todas opcionales:

Desarrollo

Para ejecutar el servidor desde un checkout del código fuente en lugar del paquete publicado, usa uv:

uv sync
uv run smt-sudoku-mcp

Consulta AGENTS.md para notas de arquitectura y el conjunto completo de comandos de desarrollo (just -l).

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas.

Licencia

MIT.