Soduku Solver MCP Server

Instructions

Implementation Reference

• src/sodukusolver/server.py:241-282 (handler)

  The execution handler for the 'solve-sudoku' tool. It retrieves a stored Sudoku puzzle by name, makes a copy, solves it using solveSudoku, stores the solved version, notifies of changes, and returns the formatted solution or error messages.

  elif name == "solve-sudoku":
      puzzle_name = arguments.get("name")
      
      if not puzzle_name:
          raise ValueError("Missing puzzle name")
          
      if puzzle_name not in sudoku_puzzles:
          return [
              types.TextContent(
                  type="text",
                  text=f"Sudoku puzzle '{puzzle_name}' not found",
              )
          ]
          
      # Make a copy of the grid to solve
      grid = [row[:] for row in sudoku_puzzles[puzzle_name]]
      
      # Solve the puzzle
      if solveSudoku(grid):
          # Store the solved puzzle with a new name
          solved_name = f"{puzzle_name}_solved"
          sudoku_puzzles[solved_name] = grid
          
          # Notify clients that resources have changed
          await server.request_context.session.send_resource_list_changed()
          
          # Return formatted solution
          formatted_grid = format_sudoku_grid(grid)
          
          return [
              types.TextContent(
                  type="text",
                  text=f"Solved Sudoku puzzle '{puzzle_name}':\n\n{formatted_grid}",
              )
          ]
      else:
          return [
              types.TextContent(
                  type="text",
                  text=f"No solution found for Sudoku puzzle '{puzzle_name}'",
              )
          ]

• src/sodukusolver/server.py:152-162 (registration)

  Registration of the 'solve-sudoku' tool in the list_tools method, including its name, description, and input schema requiring a 'name' parameter.

  types.Tool(
      name="solve-sudoku",
      description="Solve a Sudoku puzzle",
      inputSchema={
          "type": "object",
          "properties": {
              "name": {"type": "string", "description": "Name of the puzzle to solve"},
          },
          "required": ["name"],
      },
  ),

• src/sodukusolver/server.py:155-161 (schema)

  JSON schema for the 'solve-sudoku' tool input, defining a required 'name' string parameter.

  inputSchema={
      "type": "object",
      "properties": {
          "name": {"type": "string", "description": "Name of the puzzle to solve"},
      },
      "required": ["name"],
  },

• src/sodukusolver/solver.py:70-93 (helper)

  Core helper function that implements the Sudoku solver using backtracking with bitmask optimization for rows, columns, and 3x3 boxes.

  def solveSudoku(mat):
      """
      Solve a Sudoku puzzle.
      
      Args:
          mat: The Sudoku grid (9x9 matrix) with 0s for empty cells
          
      Returns:
          bool: True if solved successfully, False otherwise
      """
      n = len(mat)
      row = [0] * n
      col = [0] * n
      box = [0] * n
  
      # Set the bits in bitmasks for values that are initially present
      for i in range(n):
          for j in range(n):
              if mat[i][j] != 0:
                  row[i] |= (1 << mat[i][j])
                  col[j] |= (1 << mat[i][j])
                  box[(i // 3) * 3 + j // 3] |= (1 << mat[i][j])
  
      return sudokuSolverRec(mat, 0, 0, row, col, box)